From e0b9161ec81810282c46ac136738fc10975e805f Mon Sep 17 00:00:00 2001 From: RDW Date: Sat, 4 Feb 2023 13:55:14 +0100 Subject: [PATCH 01/12] Docs: Create a new category for the API documentation --- docs/references/api/_category_.json | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 docs/references/api/_category_.json diff --git a/docs/references/api/_category_.json b/docs/references/api/_category_.json new file mode 100644 index 00000000..3e5bd0ad --- /dev/null +++ b/docs/references/api/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "API", + "position": 0, + "link": { + "type": "generated-index", + "description": "This page lists the Lua APIs available to Evo-based applications" + } +} From 62efce7507b7b4032fd9c6e4a322852fa70d6757 Mon Sep 17 00:00:00 2001 From: RDW Date: Sat, 4 Feb 2023 14:02:53 +0100 Subject: [PATCH 02/12] UI: Add a link to the API reference to the navigation bar --- docusaurus.config.js | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docusaurus.config.js b/docusaurus.config.js index 106eba40..9234d792 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -61,6 +61,11 @@ const config = { label: "Documentation", position: "left", }, + { + href: "/docs/category/api", + label: "API Overview", + position: "left", + }, { href: "https://github.com/evo-lua", label: "GitHub", From db132950089040016fc74397a0a69a33e1c78cc5 Mon Sep 17 00:00:00 2001 From: RDW Date: Sat, 4 Feb 2023 13:55:33 +0100 Subject: [PATCH 03/12] Docs: Add an API reference for the transform library --- docs/references/api/transform.md | 213 +++++++++++++++++++++++++++++++ 1 file changed, 213 insertions(+) create mode 100644 docs/references/api/transform.md diff --git a/docs/references/api/transform.md b/docs/references/api/transform.md new file mode 100644 index 00000000..3a121949 --- /dev/null +++ b/docs/references/api/transform.md @@ -0,0 +1,213 @@ +# transform + +Text transformation library for generating colored console output + +## Status + + + +## Availability + +This module is preloaded. You can simply `require` it: + +```lua +local transform = require("transform") +``` + +## Functions + +### black + +Returns the input string wrapped in [ANSI escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code) so that it is rendered black in supporting terminals. + + + + + + + + + + +### blackBackground + +Returns the input string wrapped in [ANSI escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code) so that it is rendered on a black background in supporting terminals. + + + + + + + + + + +### bold + +Returns the input string wrapped in [ANSI escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code) so that it is rendered with bold font in supporting terminals. + + + + + + + + + + +### brightRed + +Returns the input string wrapped in [ANSI escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code) so that it is rendered bright red in supporting terminals. + + + + + + + + + + +### brightRedBackground + +Returns the input string wrapped in [ANSI escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code) so that it is rendered on a bright red background in supporting terminals. + + + + + + + + + + +### cyan + +Returns the input string wrapped in [ANSI escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code) so that it is rendered cyan in supporting terminals. + + + + + + + + + + +### enable + +Globally enables text transformations. This operation is not applied retroactively. Text transformations are enabled by default. + +### disable + +Globally disables text transformations. This operation is not applied retroactively. Use this if your terminal can't display colors. + +### gray + +Returns the input string wrapped in [ANSI escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code) so that it is rendered gray in supporting terminals. + + + + + + + + + + +### green + +Returns the input string wrapped in [ANSI escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code) so that it is rendered green in supporting terminals. + + + + + + + + + + +### greenBackground + +Returns the input string wrapped in [ANSI escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code) so that it is rendered on a green background in supporting terminals. + + + + + + + + + + +### red + +Returns the input string wrapped in [ANSI escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code) so that it is rendered dark red in supporting terminals. + + + + + + + + + + +### underline + +Returns the input string wrapped in [ANSI escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code) so that it is rendered underlined in supporting terminals. + + + + + + + + + + +### yellow + +Returns the input string wrapped in [ANSI escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code) so that it is rendered yellow in supporting terminals. + + + + + + + + + + +### white + +Returns the input string wrapped in [ANSI escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code) so that it is rendered white in supporting terminals. + + + + + + + + + + +### whiteBackground + +Returns the input string wrapped in [ANSI escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code) so that it is rendered on a white background in supporting terminals. + + + + + + + + + + +## Changelog + +| Version | What happened? | +| :-----: | :-------------: | +| v0.0.1 | Initial release | From dd35c803ea3bcd928c80ab303d63a3774f5e5dbc Mon Sep 17 00:00:00 2001 From: RDW Date: Sat, 4 Feb 2023 13:55:36 +0100 Subject: [PATCH 04/12] Docs: Add an API reference for the uv library --- docs/references/api/uv.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 docs/references/api/uv.md diff --git a/docs/references/api/uv.md b/docs/references/api/uv.md new file mode 100644 index 00000000..aab2098c --- /dev/null +++ b/docs/references/api/uv.md @@ -0,0 +1,25 @@ +# uv + +Lua bindings for the embedded libuv library + +## Status + + + +## Availability + +This module is preloaded. You can simply `require` it: + +```lua +local uv = require("uv") +``` + +## Functions + +The API documentation can be found here: [https://github.com/luvit/luv/blob/master/docs.md](https://github.com/luvit/luv/blob/master/docs.md) + +## Changelog + +| Version | What happened? | +| :-----: | :-------------: | +| v0.0.1 | Initial release | From 36127bc1fd24afc1e44f9a66a2c5511da03a5f06 Mon Sep 17 00:00:00 2001 From: RDW Date: Sat, 4 Feb 2023 13:55:39 +0100 Subject: [PATCH 05/12] Docs: Add an API reference for the validation library --- docs/references/api/validation.md | 111 ++++++++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 docs/references/api/validation.md diff --git a/docs/references/api/validation.md b/docs/references/api/validation.md new file mode 100644 index 00000000..c89d66c5 --- /dev/null +++ b/docs/references/api/validation.md @@ -0,0 +1,111 @@ +# validation + +Tiny utility library for validating function arguments + +## Status + + + +## Availability + +This module is preloaded. You can simply `require` it: + +```lua +local validation = require("validation") +``` + +## Functions + +### validateBoolean + +Raises an error if the given argument is not a `boolean` value. + + + + + + + + +### validateFunction + +Raises an error if the given argument is not a `function` value. + + + + + + + + +### validateNumber + +Raises an error if the given argument is not a `number` value. + + + + + + + + +### validateString + +Raises an error if the given argument is not a `string` value. + + + + + + + + +### validateStruct + +Raises an error if the given argument is not a `cdata` value. The exact `ctype` is not checked in any way. + + + + + + + + +### validateTable + +Raises an error if the given argument is not a `table` value. + + + + + + + + +### validateThread + +Raises an error if the given argument is not a `thread` value (coroutine). + + + + + + + + +### validateUserdata + +Raises an error if the given argument is not a `userdata` value. + + + + + + + + +## Changelog + +| Version | What happened? | +| :-----: | :-------------: | +| v0.0.1 | Initial release | From 83f7704ee9196b9a3dd2ae5ca93881ae99c55d82 Mon Sep 17 00:00:00 2001 From: RDW Date: Sat, 4 Feb 2023 13:55:45 +0100 Subject: [PATCH 06/12] Docs: Add an API reference for the assertions library --- docs/references/api/assertions.md | 188 ++++++++++++++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 docs/references/api/assertions.md diff --git a/docs/references/api/assertions.md b/docs/references/api/assertions.md new file mode 100644 index 00000000..d2286d89 --- /dev/null +++ b/docs/references/api/assertions.md @@ -0,0 +1,188 @@ +# assertions + +Builtin assertion library designed for more convenient unit testing + +## Status + + + +## Availability + +This module is preloaded. You can simply `require` it: + +```lua +local assertions = require("assertions") +``` + +## Functions + +### assertCallsFunction + +Raises an error if the function passed doesn't call the target function. The function has to be executed in order to determine this fact. + + + + + + + + +### assertDoesNotThrow + +Raises an error if the function passed throws (raises an error) itself. The purpose of this is to generate standardized error messages. + + + + + + + +### assertEquals + +Raises an error if the two passed values are not identical. This is a catch-all handler that uses the more specialized assertions internally. + + + + + + + + +### assertEqualBooleans + +Raises an error if the two passed values do not represent the same `boolean` value. + + + + + + + + +### assertEqualBytes + +Raises an error if the two passed values do not represent the same `cdata` bytes. Use [assertEqualPointers](#assertequalpointers) to compare only the pointer. + + + + + + + + +### assertEqualFunctions + +Raises an error if the two passed values do not represent the same `function` value. + + + + + + + + +### assertEqualNumbers + +Raises an error if the two passed values do not represent the same `number` value. + + + + + + + + +### assertEqualPointers + +Raises an error if the two passed values do not represent the same `cdata` pointer. Use [assertEqualBytes](#assertequalbytes) to compare them by value. + + + + + + + + +### assertEqualStrings + +Raises an error if the two passed values do not represent the same `string` value. Supports LuaJIT string buffers and `cdata` strings. + + + + + + + + +### assertEqualTables + +Raises an error if the two passed values do not represent the same `table` value. Supports deep table comparisons. + + + + + + + + +### assertFailure + +Raises an error if the function passed does not return a "failure" type (`nil` and an error message). + + + + + + + + +### assertFalse + +Raises an error if the value passed is not exactly `false`. + + + + + + + +### assertNil + +Raises an error if the value passed is not exactly `nil`. + + + + + + + +### assertThrows + +Raises an error if the function passed does not itself raise an error (with the expected error message). + + + + + + + + +### assertTrue + +Raises an error if the value passed is not exactly `true`. + + + + + + + +### export + +Exports all of the assertions in this module to the global Lua environment. Use this if you don't want to `require` them in every test. + +## Changelog + +| Version | What happened? | +| :-----: | :-------------: | +| v0.0.1 | Initial release | From 8f63e60b04829296305b16e26f51d552a77b65fa Mon Sep 17 00:00:00 2001 From: RDW Date: Sun, 5 Feb 2023 06:07:41 +0100 Subject: [PATCH 07/12] Docs: Add an API reference for the inspect library --- docs/references/api/inspect.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 docs/references/api/inspect.md diff --git a/docs/references/api/inspect.md b/docs/references/api/inspect.md new file mode 100644 index 00000000..df820aad --- /dev/null +++ b/docs/references/api/inspect.md @@ -0,0 +1,25 @@ +# inspect + +Human-readable representation of Lua tables + +## Status + + + +## Availability + +This module is preloaded. You can simply `require` it: + +```lua +local inspect = require("inspect") +``` + +## Functions + +The API documentation can be found here: [https://github.com/kikito/inspect.lua](https://github.com/kikito/inspect.lua) + +## Changelog + +| Version | What happened? | +| :-----: | :-------------: | +| v0.0.1 | Initial release | From 7aba3f39f3a57be61162f5e3626696ffd4ac087b Mon Sep 17 00:00:00 2001 From: RDW Date: Sun, 5 Feb 2023 06:07:46 +0100 Subject: [PATCH 08/12] Docs: Add an API reference for global aliases --- docs/references/api/globals.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 docs/references/api/globals.md diff --git a/docs/references/api/globals.md b/docs/references/api/globals.md new file mode 100644 index 00000000..0511ddb7 --- /dev/null +++ b/docs/references/api/globals.md @@ -0,0 +1,33 @@ +--- +sidebar_position: 20 +--- + +# Globals + +Convenient shorthands for some frequently-used functionality + +## Functions + +### dump + +Alias for [debug.dump(...)](/docs/references/api/extensions#debugdump). + +### format + +Alias for `string.format(...)`. + +### printf + +Alias for `print(string.format(...))`. + +## Tables + +### buffer + +Alias for `string.buffer` (LuaJIT builtin). + +## Changelog + +| Version | What happened? | +| :-----: | :-------------: | +| v0.0.1 | Initial release | From c1823857ac7671627aaae6db5f5badad3b439759 Mon Sep 17 00:00:00 2001 From: RDW Date: Sun, 5 Feb 2023 06:07:50 +0100 Subject: [PATCH 09/12] Docs: Add an API reference for Lua extensions --- docs/references/api/extensions.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 docs/references/api/extensions.md diff --git a/docs/references/api/extensions.md b/docs/references/api/extensions.md new file mode 100644 index 00000000..65b3bb48 --- /dev/null +++ b/docs/references/api/extensions.md @@ -0,0 +1,22 @@ +--- +sidebar_position: 10 +--- + +# Extensions + +Unofficial extensions to the Lua standard libraries + +## Debug Library + +### debug.dump + +Prints a human-readable string representation of the given object. Mostly useful for dumping tables, but unsuitable for serialization purposes. The output format cannot be considered stable. Currently uses [inspect](/docs/references/api/inspect) internally, though this may change in the future. + + + + + + + + + From b6a9ddeed64ebc8e80174e82292de5eeb32790a8 Mon Sep 17 00:00:00 2001 From: RDW Date: Sat, 4 Feb 2023 13:55:42 +0100 Subject: [PATCH 10/12] Docs: Add an API reference for the webview library This needs a review, but I'll save it for when the bindings are streamlined (the current implementation is more of a proof-of-concept). --- docs/references/api/webview.md | 195 +++++++++++++++++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 docs/references/api/webview.md diff --git a/docs/references/api/webview.md b/docs/references/api/webview.md new file mode 100644 index 00000000..5cad79df --- /dev/null +++ b/docs/references/api/webview.md @@ -0,0 +1,195 @@ +# webview + +LuaJIT bindings for the embedded webview library + + + +## Status + + + +## Availability + +This module is preloaded. You can simply `require` it: + +```lua +local webview = require("webview") +``` + +## Fields + +### cdefs + +A string representing the C type definitions that were used to load the FFI bindings. Do not attempt to `ffi.load` them manually. + +### bindings + +A pointer to the statically-loaded exports table that exposes the bound functions to Lua. For more details, see [this note](/docs/background-information/luajit/static-ffi-bindings). + +## Functions + +### initialize + +Initializes the bindings by loading the [C type definitions](#cdefs). Automatically called by the runtime when it sets up the Lua environment + +## Native Bindings + +All C functions listed here can be accessed via `webview.bindings` and must be called with the appropriate `cdata` values. + +### bind + +```c +// Binds a native C callback so that it will appear under the given name as a +// global JavaScript function. Internally it uses webview_init(). Callback +// receives a request string and a user-provided argument pointer. Request +// string is a JSON array of all the arguments passed to the JavaScript +// function. +WEBVIEW_API void webview_bind(webview_t w, const char *name, + void (*fn)(const char *seq, const char *req, + void *arg), + void *arg); +``` + +### create + +```c +// Creates a new webview instance. If debug is non-zero - developer tools will +// be enabled (if the platform supports them). Window parameter can be a +// pointer to the native window handle. If it's non-null - then child WebView +// is embedded into the given parent window. Otherwise a new window is created. +// Depending on the platform, a GtkWindow, NSWindow or HWND pointer can be +// passed here. Returns null on failure. Creation can fail for various reasons +// such as when required runtime dependencies are missing or when window creation +// fails. + +WEBVIEW_API webview_t webview_create(int debug, void *window); +``` + +### destroy + +```c +// Destroys a webview and closes the native window. +WEBVIEW_API void webview_destroy(webview_t w); +``` + +### dispatch + +```c +// Posts a function to be executed on the main thread. You normally do not need +// to call this function, unless you want to tweak the native window. +WEBVIEW_API void +webview_dispatch(webview_t w, void (*fn)(webview_t w, void *arg), void *arg); +``` + +### eval + +```c +// Evaluates arbitrary JavaScript code. Evaluation happens asynchronously, also +// the result of the expression is ignored. Use RPC bindings if you want to +// receive notifications about the results of the evaluation. +WEBVIEW_API void webview_eval(webview_t w, const char *js); +``` + +### get_window + +```c +// Returns a native window handle pointer. When using GTK backend the pointer +// is GtkWindow pointer, when using Cocoa backend the pointer is NSWindow +// pointer, when using Win32 backend the pointer is HWND pointer. +WEBVIEW_API void *webview_get_window(webview_t w); +``` + +### init + +```c +// Injects JavaScript code at the initialization of the new page. Every time +// the webview will open a the new page - this initialization code will be +// executed. It is guaranteed that code is executed before window.onload. +WEBVIEW_API void webview_init(webview_t w, const char *js); +``` + +### navigate + +```c +// Navigates webview to the given URL. URL may be a properly encoded data URI. +// Examples: +// webview_navigate(w, "https://github.com/webview/webview"); +// webview_navigate(w, "data:text/html,%3Ch1%3EHello%3C%2Fh1%3E"); +// webview_navigate(w, "data:text/html;base64,PGgxPkhlbGxvPC9oMT4="); +WEBVIEW_API void webview_navigate(webview_t w, const char *url); +``` + +### return + +```c +// Allows to return a value from the native binding. Original request pointer +// must be provided to help internal RPC engine match requests with responses. +// If status is zero - result is expected to be a valid JSON result value. +// If status is not zero - result is an error JSON object. +WEBVIEW_API void webview_return(webview_t w, const char *seq, int status, + const char *result); +``` + +### run + +```c +// Runs the main loop until it's terminated. After this function exits - you +// must destroy the webview. +WEBVIEW_API void webview_run(webview_t w); +``` + +### set_html + +```c +// Set webview HTML directly. +// Example: webview_set_html(w, "

Hello

"); +WEBVIEW_API void webview_set_html(webview_t w, const char *html); +``` + +### set_size + +```c +// Window size hints +#define WEBVIEW_HINT_NONE 0 // Width and height are default size +#define WEBVIEW_HINT_MIN 1 // Width and height are minimum bounds +#define WEBVIEW_HINT_MAX 2 // Width and height are maximum bounds +#define WEBVIEW_HINT_FIXED 3 // Window size can not be changed by a user +// Updates native window size. See WEBVIEW_HINT constants. +WEBVIEW_API void webview_set_size(webview_t w, int width, int height, + int hints); +``` + +### set_title + +```c +// Updates the title of the native window. Must be called from the UI thread. +WEBVIEW_API void webview_set_title(webview_t w, const char *title); +``` + +### terminate + +```c +// Stops the main loop. It is safe to call this function from another other +// background thread. +WEBVIEW_API void webview_terminate(webview_t w); +``` + +### unbind + +```c +// Removes a native C callback that was previously set by webview_bind. +WEBVIEW_API void webview_unbind(webview_t w, const char *name); +``` + +### version + +```c +// Get the library's version information. +WEBVIEW_API const webview_version_info_t *webview_version(); +``` + +## Changelog + +| Version | What happened? | +| :-----: | :-------------: | +| v0.0.1 | Initial release | From 8213eed25e22638de330e8de0dfb6a712b8e747f Mon Sep 17 00:00:00 2001 From: RDW Date: Sun, 5 Feb 2023 12:42:45 +0100 Subject: [PATCH 11/12] Theme: Swizzle the builtin MDXComponents component This is an awkward way of getting to auto-import the custom components that are embedded in the markdown files... but there's no better way of doing this apparently (wrapping this component is "forbidden", pff). I don't plan on customizing anything here really, so hopefully the maintenance overhead for updating the index will be limited. --- src/theme/MDXComponents/A.d.ts | 3 ++ src/theme/MDXComponents/A.js | 5 +++ src/theme/MDXComponents/Code.d.ts | 3 ++ src/theme/MDXComponents/Code.js | 42 +++++++++++++++++++ src/theme/MDXComponents/Details.d.ts | 3 ++ src/theme/MDXComponents/Details.js | 16 +++++++ src/theme/MDXComponents/Head.d.ts | 3 ++ src/theme/MDXComponents/Head.js | 17 ++++++++ src/theme/MDXComponents/Heading.d.ts | 3 ++ src/theme/MDXComponents/Heading.js | 5 +++ src/theme/MDXComponents/Img/index.js | 16 +++++++ src/theme/MDXComponents/Img/styles.module.css | 3 ++ src/theme/MDXComponents/Pre.d.ts | 3 ++ src/theme/MDXComponents/Pre.js | 13 ++++++ src/theme/MDXComponents/Ul/index.js | 15 +++++++ src/theme/MDXComponents/Ul/styles.module.css | 7 ++++ src/theme/MDXComponents/index.d.ts | 3 ++ src/theme/MDXComponents/index.js | 30 +++++++++++++ 18 files changed, 190 insertions(+) create mode 100644 src/theme/MDXComponents/A.d.ts create mode 100644 src/theme/MDXComponents/A.js create mode 100644 src/theme/MDXComponents/Code.d.ts create mode 100644 src/theme/MDXComponents/Code.js create mode 100644 src/theme/MDXComponents/Details.d.ts create mode 100644 src/theme/MDXComponents/Details.js create mode 100644 src/theme/MDXComponents/Head.d.ts create mode 100644 src/theme/MDXComponents/Head.js create mode 100644 src/theme/MDXComponents/Heading.d.ts create mode 100644 src/theme/MDXComponents/Heading.js create mode 100644 src/theme/MDXComponents/Img/index.js create mode 100644 src/theme/MDXComponents/Img/styles.module.css create mode 100644 src/theme/MDXComponents/Pre.d.ts create mode 100644 src/theme/MDXComponents/Pre.js create mode 100644 src/theme/MDXComponents/Ul/index.js create mode 100644 src/theme/MDXComponents/Ul/styles.module.css create mode 100644 src/theme/MDXComponents/index.d.ts create mode 100644 src/theme/MDXComponents/index.js diff --git a/src/theme/MDXComponents/A.d.ts b/src/theme/MDXComponents/A.d.ts new file mode 100644 index 00000000..2924abb6 --- /dev/null +++ b/src/theme/MDXComponents/A.d.ts @@ -0,0 +1,3 @@ +/// +import type { Props } from "@theme/MDXComponents/A"; +export default function MDXA(props: Props): JSX.Element; diff --git a/src/theme/MDXComponents/A.js b/src/theme/MDXComponents/A.js new file mode 100644 index 00000000..77e8b148 --- /dev/null +++ b/src/theme/MDXComponents/A.js @@ -0,0 +1,5 @@ +import React from "react"; +import Link from "@docusaurus/Link"; +export default function MDXA(props) { + return ; +} diff --git a/src/theme/MDXComponents/Code.d.ts b/src/theme/MDXComponents/Code.d.ts new file mode 100644 index 00000000..bffbc7c7 --- /dev/null +++ b/src/theme/MDXComponents/Code.d.ts @@ -0,0 +1,3 @@ +/// +import type { Props } from "@theme/MDXComponents/Code"; +export default function MDXCode(props: Props): JSX.Element; diff --git a/src/theme/MDXComponents/Code.js b/src/theme/MDXComponents/Code.js new file mode 100644 index 00000000..13f62aa4 --- /dev/null +++ b/src/theme/MDXComponents/Code.js @@ -0,0 +1,42 @@ +import React, { isValidElement } from "react"; +import CodeBlock from "@theme/CodeBlock"; +export default function MDXCode(props) { + const inlineElements = [ + "a", + "abbr", + "b", + "br", + "button", + "cite", + "code", + "del", + "dfn", + "em", + "i", + "img", + "input", + "ins", + "kbd", + "label", + "object", + "output", + "q", + "ruby", + "s", + "small", + "span", + "strong", + "sub", + "sup", + "time", + "u", + "var", + "wbr", + ]; + const shouldBeInline = React.Children.toArray(props.children).every( + (el) => + (typeof el === "string" && !el.includes("\n")) || + (isValidElement(el) && inlineElements.includes(el.props?.mdxType)) + ); + return shouldBeInline ? : ; +} diff --git a/src/theme/MDXComponents/Details.d.ts b/src/theme/MDXComponents/Details.d.ts new file mode 100644 index 00000000..3d2301e2 --- /dev/null +++ b/src/theme/MDXComponents/Details.d.ts @@ -0,0 +1,3 @@ +/// +import type { Props } from "@theme/MDXComponents/Details"; +export default function MDXDetails(props: Props): JSX.Element; diff --git a/src/theme/MDXComponents/Details.js b/src/theme/MDXComponents/Details.js new file mode 100644 index 00000000..02d1d92f --- /dev/null +++ b/src/theme/MDXComponents/Details.js @@ -0,0 +1,16 @@ +import React from "react"; +import Details from "@theme/Details"; +export default function MDXDetails(props) { + const items = React.Children.toArray(props.children); + // Split summary item from the rest to pass it as a separate prop to the + // Details theme component + const summary = items.find( + (item) => React.isValidElement(item) && item.props?.mdxType === "summary" + ); + const children = <>{items.filter((item) => item !== summary)}; + return ( +
+ {children} +
+ ); +} diff --git a/src/theme/MDXComponents/Head.d.ts b/src/theme/MDXComponents/Head.d.ts new file mode 100644 index 00000000..22f5ec87 --- /dev/null +++ b/src/theme/MDXComponents/Head.d.ts @@ -0,0 +1,3 @@ +/// +import type { Props } from "@theme/MDXComponents/Head"; +export default function MDXHead(props: Props): JSX.Element; diff --git a/src/theme/MDXComponents/Head.js b/src/theme/MDXComponents/Head.js new file mode 100644 index 00000000..63cbf341 --- /dev/null +++ b/src/theme/MDXComponents/Head.js @@ -0,0 +1,17 @@ +import React from "react"; +import Head from "@docusaurus/Head"; +// MDX elements are wrapped through the MDX pragma. In some cases (notably usage +// with Head/Helmet) we need to unwrap those elements. +function unwrapMDXElement(element) { + if (element.props?.mdxType && element.props.originalType) { + const { mdxType, originalType, ...newProps } = element.props; + return React.createElement(element.props.originalType, newProps); + } + return element; +} +export default function MDXHead(props) { + const unwrappedChildren = React.Children.map(props.children, (child) => + React.isValidElement(child) ? unwrapMDXElement(child) : child + ); + return {unwrappedChildren}; +} diff --git a/src/theme/MDXComponents/Heading.d.ts b/src/theme/MDXComponents/Heading.d.ts new file mode 100644 index 00000000..fc7d8f95 --- /dev/null +++ b/src/theme/MDXComponents/Heading.d.ts @@ -0,0 +1,3 @@ +/// +import type { Props } from "@theme/MDXComponents/Heading"; +export default function MDXHeading(props: Props): JSX.Element; diff --git a/src/theme/MDXComponents/Heading.js b/src/theme/MDXComponents/Heading.js new file mode 100644 index 00000000..3e9e8c78 --- /dev/null +++ b/src/theme/MDXComponents/Heading.js @@ -0,0 +1,5 @@ +import React from "react"; +import Heading from "@theme/Heading"; +export default function MDXHeading(props) { + return ; +} diff --git a/src/theme/MDXComponents/Img/index.js b/src/theme/MDXComponents/Img/index.js new file mode 100644 index 00000000..0c32b265 --- /dev/null +++ b/src/theme/MDXComponents/Img/index.js @@ -0,0 +1,16 @@ +import React from "react"; +import clsx from "clsx"; +import styles from "./styles.module.css"; +function transformImgClassName(className) { + return clsx(className, styles.img); +} +export default function MDXImg(props) { + return ( + // eslint-disable-next-line jsx-a11y/alt-text + + ); +} diff --git a/src/theme/MDXComponents/Img/styles.module.css b/src/theme/MDXComponents/Img/styles.module.css new file mode 100644 index 00000000..2e4c258f --- /dev/null +++ b/src/theme/MDXComponents/Img/styles.module.css @@ -0,0 +1,3 @@ +.img { + height: auto; +} diff --git a/src/theme/MDXComponents/Pre.d.ts b/src/theme/MDXComponents/Pre.d.ts new file mode 100644 index 00000000..82acfadd --- /dev/null +++ b/src/theme/MDXComponents/Pre.d.ts @@ -0,0 +1,3 @@ +/// +import type { Props } from "@theme/MDXComponents/Pre"; +export default function MDXPre(props: Props): JSX.Element; diff --git a/src/theme/MDXComponents/Pre.js b/src/theme/MDXComponents/Pre.js new file mode 100644 index 00000000..d37a4d1c --- /dev/null +++ b/src/theme/MDXComponents/Pre.js @@ -0,0 +1,13 @@ +import React, { isValidElement } from "react"; +import CodeBlock from "@theme/CodeBlock"; +export default function MDXPre(props) { + return ( + + ); +} diff --git a/src/theme/MDXComponents/Ul/index.js b/src/theme/MDXComponents/Ul/index.js new file mode 100644 index 00000000..c6f77ef6 --- /dev/null +++ b/src/theme/MDXComponents/Ul/index.js @@ -0,0 +1,15 @@ +import React from "react"; +import clsx from "clsx"; +import styles from "./styles.module.css"; +function transformUlClassName(className) { + return clsx( + className, + // This class is set globally by GitHub/MDX. We keep the global class, and + // add another class to get a task list without the default ul styling + // See https://github.com/syntax-tree/mdast-util-to-hast/issues/28 + className?.includes("contains-task-list") && styles.containsTaskList + ); +} +export default function MDXUl(props) { + return
    ; +} diff --git a/src/theme/MDXComponents/Ul/styles.module.css b/src/theme/MDXComponents/Ul/styles.module.css new file mode 100644 index 00000000..0e0eec9d --- /dev/null +++ b/src/theme/MDXComponents/Ul/styles.module.css @@ -0,0 +1,7 @@ +.containsTaskList { + list-style: none; +} + +:not(.containsTaskList > li) > .containsTaskList { + padding-left: 0; +} diff --git a/src/theme/MDXComponents/index.d.ts b/src/theme/MDXComponents/index.d.ts new file mode 100644 index 00000000..1bcdb51d --- /dev/null +++ b/src/theme/MDXComponents/index.d.ts @@ -0,0 +1,3 @@ +import type { MDXComponentsObject } from "@theme/MDXComponents"; +declare const MDXComponents: MDXComponentsObject; +export default MDXComponents; diff --git a/src/theme/MDXComponents/index.js b/src/theme/MDXComponents/index.js new file mode 100644 index 00000000..2e6c3871 --- /dev/null +++ b/src/theme/MDXComponents/index.js @@ -0,0 +1,30 @@ +import React from "react"; +import MDXHead from "@theme/MDXComponents/Head"; +import MDXCode from "@theme/MDXComponents/Code"; +import MDXA from "@theme/MDXComponents/A"; +import MDXPre from "@theme/MDXComponents/Pre"; +import MDXDetails from "@theme/MDXComponents/Details"; +import MDXHeading from "@theme/MDXComponents/Heading"; +import MDXUl from "@theme/MDXComponents/Ul"; +import MDXImg from "@theme/MDXComponents/Img"; + +import Admonition from "@theme/Admonition"; +import Mermaid from "@theme/Mermaid"; +const MDXComponents = { + head: MDXHead, + code: MDXCode, + a: MDXA, + pre: MDXPre, + details: MDXDetails, + ul: MDXUl, + img: MDXImg, + h1: (props) => , + h2: (props) => , + h3: (props) => , + h4: (props) => , + h5: (props) => , + h6: (props) => , + admonition: Admonition, + mermaid: Mermaid, +}; +export default MDXComponents; From e32912fe4be292601d74909ddf0e54cce011ba8c Mon Sep 17 00:00:00 2001 From: RDW Date: Sun, 5 Feb 2023 12:43:03 +0100 Subject: [PATCH 12/12] Theme: Implement React components for the API docs I don't know React very well so the code is likely bad... but it works. --- src/components/API/API.jsx | 244 +++++++++++++++++++++++++++ src/components/API/styles.module.css | 112 ++++++++++++ src/css/layouts.css | 4 + src/theme/MDXComponents/index.js | 29 ++++ 4 files changed, 389 insertions(+) create mode 100644 src/components/API/API.jsx create mode 100644 src/components/API/styles.module.css diff --git a/src/components/API/API.jsx b/src/components/API/API.jsx new file mode 100644 index 00000000..5d6395e5 --- /dev/null +++ b/src/components/API/API.jsx @@ -0,0 +1,244 @@ +import React from "react"; + +import styles from "./styles.module.css"; + +export const Function = ({ children }) => ( +
    {children}
    +); + +class NilableInfo extends React.Component { + render() { + return <>?; + } +} + +class OptionalInfo extends React.Component { + render() { + return <>?; + } +} + +class Parameter extends React.Component { + render() { + let displayName = this.props.name; + let displayType = this.props.type; + + if (this.props.varargs) { + displayName = "..."; + displayType = ( + + varargs + + ); + } + + return ( + + {this.props.index} + {displayName} + + {displayType ? displayType : "any"} + {this.props.optional ? : ""} + + {this.props.fallback ? this.props.fallback : ""} + + ); + } +} + +class Parameters extends React.Component { + hasChildren() { + return this.props.children !== undefined; + } + render() { + return ( + + + + + + + + + + + + {this.props.children} + +
    Arguments
    #NameTypeFallback
    + ); + } +} + +class Returns extends React.Component { + render() { + return ( + + + + + + + + + + + {this.props.children} + +
    Return values
    #NameType
    + ); + } +} +class Return extends React.Component { + render() { + return ( + + {this.props.index} + {this.props.name} + + {this.props.type ? this.props.type : "any"} + {this.props.optional ? : ""} + + + ); + } +} + +class Struct extends React.Component { + render() { + return ( + <> + + + + + + + + + + {this.props.children} + +
    {this.props.name}
    FieldType
    + + ); + } +} + +class Member extends React.Component { + render() { + return ( + + {this.props.name} + + {this.props.type ? this.props.type : "any"} + {this.props.optional ? : ""} + + + ); + } +} + +class Experimental extends React.Component { + render() { + return ( + <> +
    + Experimental: Functionality may change for any reason, without + semantic versioning guarantees +
    + + ); + } +} + +class Stable extends React.Component { + render() { + return ( + <> +
    + Stable: Functionality is covered by semantic versioning guarantees and + unlikely to see breaking changes +
    + + ); + } +} + +class Deprecated extends React.Component { + render() { + return ( + <> +
    + Deprecated: Functionality is maintained for backwards compatibility + only, but covered by semantic versioning guarantees +
    + + ); + } +} + +class External extends React.Component { + render() { + return ( + <> +
    + External: Functionality is provided by a third-party library, which + may or may not give semantic versioning guarantees +
    + + ); + } +} + +import Admonition from "@theme/Admonition"; + +class FFI extends React.Component { + render() { + return ( + <> + + This is a low-level module; misuse can easily crash the runtime! + + + ); + } +} + +export { + Parameters, + Parameter, + Returns, + Return, + Struct, + Member, + Experimental, + Stable, + Deprecated, + External, + FFI, +}; diff --git a/src/components/API/styles.module.css b/src/components/API/styles.module.css new file mode 100644 index 00000000..44a2199c --- /dev/null +++ b/src/components/API/styles.module.css @@ -0,0 +1,112 @@ +.function { + display: flex; +} + +.functionParametersTable, +.functionReturnValuesTable, +.structMembersTable { + font-size: 0.85em; + border-collapse: collapse; + display: inline-block; + margin: 0; + margin-right: 1.5em; + box-shadow: 1px 1px 1px 1px rgba(0, 0, 0, 0.05); +} + +/* Assumes these won't ever occur without a return or args table*/ +.structMembersTable { + margin-top: 1.5em; + margin-bottom: 0; +} + +.functionParametersTable * td, +.functionReturnValuesTable * td, +.structMembersTable * td { + padding: 0.25rem; + text-align: center; + width: 7.5rem; +} + +.functionParametersTableBody { + border-left: 0.5ex solid #00802b; +} + +.functionParametersFirstRow { + background: #00802b; + text-align: center; + color: white; +} + +.functionReturnValuesTableBody { + border-left: 0.5ex solid #006699; +} + +.functionReturnValuesFirstRow { + background: #006699; + text-align: center; + color: white; +} + +.structMembersTableBody { + border-left: 0.5ex solid #b38600; +} + +.structMembersFirstRow { + background: #b38600; + text-align: center; + color: white; +} + +.functionParametersFirstRow th, +.functionParametersHeadRow th, +.functionReturnValuesFirstRow th, +.functionReturnValuesHeadRow th, +.structMembersFirstRow th, +.structMembersHeadRow th { + padding: 0.25rem; + text-align: center; +} + +/* This must be assigned to all table cells that should include the index counter (one per row) */ +.tdCounter::before { + counter-increment: parameter-index-counter; + content: counter(parameter-index-counter); +} + +/* Whenever this tag is encountered, a new parameters table should be created (with new indices) */ +.tdCounterReset { + counter-reset: parameter-index-counter; +} + +/* The counter needs to be at the highest level in order to work (no idea why; I didn't spend much time on this) */ +body { + counter-reset: parameter-index-counter; +} + +.experimental { + border: 3px solid #d60026; + padding: 0.5rem; + color: #d60026; + font-weight: 600; +} + +.stable { + border: 3px solid #0060ff; + padding: 0.5rem; + color: #0060ff; + font-weight: 600; +} + +.deprecated { + border: 3px solid #888800; + padding: 0.5rem; + color: #888800; + font-weight: 600; +} + +.external { + border: 3px solid black; + padding: 0.5rem; + color: black; + font-weight: 600; +} diff --git a/src/css/layouts.css b/src/css/layouts.css index 80fa188d..38fed337 100644 --- a/src/css/layouts.css +++ b/src/css/layouts.css @@ -10,3 +10,7 @@ .zero-margin { margin: 0; } + +.hidden { + display: none; +} diff --git a/src/theme/MDXComponents/index.js b/src/theme/MDXComponents/index.js index 2e6c3871..1ab78409 100644 --- a/src/theme/MDXComponents/index.js +++ b/src/theme/MDXComponents/index.js @@ -8,6 +8,21 @@ import MDXHeading from "@theme/MDXComponents/Heading"; import MDXUl from "@theme/MDXComponents/Ul"; import MDXImg from "@theme/MDXComponents/Img"; +import { + Function, + Parameters, + Parameter, + Returns, + Return, + Struct, + Member, + Experimental, + Stable, + Deprecated, + External, + FFI, +} from "@site/src/components/API/API"; + import Admonition from "@theme/Admonition"; import Mermaid from "@theme/Mermaid"; const MDXComponents = { @@ -26,5 +41,19 @@ const MDXComponents = { h6: (props) => , admonition: Admonition, mermaid: Mermaid, + + // Extensions go here + Function: Function, + Parameters: Parameters, + Parameter: Parameter, + Returns: Returns, + Return: Return, + Struct: Struct, + Member: Member, + Experimental: Experimental, + Stable: Stable, + Deprecated: Deprecated, + External: External, + FFI: FFI, }; export default MDXComponents;