From 30fd4acf3752a428583dfa40c554d8de12a4b487 Mon Sep 17 00:00:00 2001 From: Kingkor Roy Tirtho Date: Thu, 14 Aug 2025 21:21:09 +0600 Subject: [PATCH] docs: add plugin API docs --- .../components/navigation/DocSideBar.astro | 7 +- .../src/components/navigation/TopBar.astro | 5 +- .../components/navigation/sidebar-button.tsx | 2 +- .../src/content/docs/plugin-apis/forms.mdx | 72 ++++++++++++ .../content/docs/plugin-apis/localstorage.mdx | 103 ++++++++++++++++++ .../src/content/docs/plugin-apis/timezone.mdx | 37 +++++++ .../src/content/docs/plugin-apis/webview.mdx | 75 +++++++++++++ 7 files changed, 292 insertions(+), 9 deletions(-) create mode 100644 website/src/content/docs/plugin-apis/forms.mdx create mode 100644 website/src/content/docs/plugin-apis/localstorage.mdx create mode 100644 website/src/content/docs/plugin-apis/timezone.mdx create mode 100644 website/src/content/docs/plugin-apis/webview.mdx diff --git a/website/src/components/navigation/DocSideBar.astro b/website/src/components/navigation/DocSideBar.astro index c5a24823..d30b8fac 100644 --- a/website/src/components/navigation/DocSideBar.astro +++ b/website/src/components/navigation/DocSideBar.astro @@ -58,13 +58,8 @@ const sections: [ ][] = [ ["Get Started", "get-started/", queryCollection], ["Developing Plugins", "developing-plugins/", queryCollection], + ["Plugin APIs", "plugin-apis/", queryCollection], ["Reference", "reference/", queryCollection], - // ["Design System", "design/", queryCollection], - // ["Tailwind Components", "tailwind/", queryCollection], - // ["Functional Components", "components/", queryMetaCollection], - // ["Headless Components", "headless/", queryCollection], - // ["Integrations", "integrations/", queryMetaCollection], - // ["Resources", "resources/", queryCollection], ]; // Build navigation dynamically diff --git a/website/src/components/navigation/TopBar.astro b/website/src/components/navigation/TopBar.astro index 3da5feab..98319f28 100644 --- a/website/src/components/navigation/TopBar.astro +++ b/website/src/components/navigation/TopBar.astro @@ -4,10 +4,11 @@ import { FaGithub } from "react-icons/fa6"; import SidebarButton from "./sidebar-button"; const pathname = Astro.url.pathname; -console.log("pathname:", pathname); --- -
+
diff --git a/website/src/components/navigation/sidebar-button.tsx b/website/src/components/navigation/sidebar-button.tsx index 96139917..850f320b 100644 --- a/website/src/components/navigation/sidebar-button.tsx +++ b/website/src/components/navigation/sidebar-button.tsx @@ -13,7 +13,7 @@ export default function SidebarButton() { return <>
diff --git a/website/src/content/docs/plugin-apis/forms.mdx b/website/src/content/docs/plugin-apis/forms.mdx new file mode 100644 index 00000000..43199023 --- /dev/null +++ b/website/src/content/docs/plugin-apis/forms.mdx @@ -0,0 +1,72 @@ +--- +layout: "layouts/DocLayout.astro" +title: Forms +description: Documentation for the Forms API for spotube plugins +order: 1 +--- + +Spotube provides a Forms API that allows plugin developers to create and manage forms within the Spotube application. + +## Usage + +Following will show a form with 2 text fields and text in between them: + +```hetu_script +import "module:spotube_plugin" as spotube + +spotube.SpotubeForm.show( + "The form page title", + [ + { + objectType: "input", + id: "name", + variant: "text", + placeholder: "Enter your name", + required: true, + }.toJson(), + { + objectType: "input", + id: "password", + variant: "password", // This will obfuscate the input + placeholder: "Enter your password", + required: true, + }.toJson(), + { + objectType: "text", + text: "This is some text after the two fields.", + }.toJson(), + ] +).then((result) { + // Handle the result + print(result) +}) +``` + +The method `spotube.SpotubeForm.show` takes a title and a list of form field declaration map. The map should be, well obviously a `Map`. +Following are field map properties: + +| Property | Type | Description | +| -------------- | ----------------- | ---------------------------------------------------------------------------------- | +| `objectType` | `text` or `input` | Type of the object, should be `text` for text fields and `input` for input fields. | +| `id` | `String` | Unique identifier for the field. (`input` type only) | +| `variant` | `String` | Variant of the field, can be `text`, `password` or `number`. (`input` type only) | +| `placeholder` | `String` | Optional placeholder text for the field. (`input` type only) | +| `required` | `Boolean` | Whether the field is required or not. (`input` type only) | +| `defaultValue` | `String` | Optional default value for the field. (`input` type only) | +| `regex` | `String` | Optional regex pattern to validate the input. (`input` type only) | +| `text` | `String` | Optional text for `text` object type. (Only applicable for `text` type) | + +The method `spotube.SpotubeForm.show` returns a following format: + +```json +[ + { + "id": "name", + "value": "John Doe" + }, + { + "id": "password", + "value": "12345678" + } +] +``` diff --git a/website/src/content/docs/plugin-apis/localstorage.mdx b/website/src/content/docs/plugin-apis/localstorage.mdx new file mode 100644 index 00000000..9df39757 --- /dev/null +++ b/website/src/content/docs/plugin-apis/localstorage.mdx @@ -0,0 +1,103 @@ +--- +layout: "layouts/DocLayout.astro" +title: LocalStorage +description: Documentation for the LocalStorage API for spotube plugins +order: 2 +--- + +The `LocalStorage` API is a plain text key/value holding persistent storage for spotube plugins. It's similar to the `localStorage` API in web browsers. +The API is a 1:1 port of [shared_preferences][shared_preferences] package from [pub.dev](https://pub.dev) (Flutter package registry) + +The only difference is that the `LocalStorage` API is 100% asynchronous. So every method returns a `Future` + +## Usage + +#### Get values + +Retrieve stored information by key: + +```hetu_script +import "module:spotube_plugin" as spotube + +var LocalStorage = spotube.LocalStorage + +// Get a string value by key +LocalStorage.getString("key").then((value) { + print("Value for 'key': $value") +}) + +// Get an integer value by key +LocalStorage.getInt("key").then((value) { + print("Value for 'key': $value") +}) + +// Get a double value by key +LocalStorage.getDouble("key").then((value) { + print("Value for 'key': $value") +}) + +// Get a boolean value by key +LocalStorage.getBool("key").then((value) { + print("Value for 'key': $value") +}) + +// Get a list of strings by key +LocalStorage.getStringList("key").then((value) { + for (var item in value) { + print("Item in list: $item") + } +}) +``` + +#### Set values + +To set or store data in the local storage, you can use the following methods: + +```hetu_script +// Set a string value by key +LocalStorage.setString("key", "value") + +// Set an integer value by key +LocalStorage.setInt("key", 42) + +// Set a double value by key +LocalStorage.setDouble("key", 3.14) + +// Set a boolean value by key +LocalStorage.setBool("key", true) + +// Set a list of strings by key +LocalStorage.setStringList("key", ["item1", "item2", "item3"]) +``` + +#### Key operations + +To remove a value from the local storage, you can use the `remove` method: + +```hetu_script +// Remove a value by key +LocalStorage.remove("key") +``` + +To clear all values from the local storage, you can use the `clear` method: + +```hetu_script +// Clear all values from local storage +LocalStorage.clear() +``` + +To check if a key exists in the local storage, you can use the `containsKey` method: + +```hetu_script +// Check if a key exists +LocalStorage.containsKey("key").then((exists) { + if (exists) { + print("Key 'key' exists in local storage") + } else { + print("Key 'key' does not exist in local storage") + } +}) +``` + +{/* Links */} +[shared_preferences]: https://pub.dev/packages/shared_preferences diff --git a/website/src/content/docs/plugin-apis/timezone.mdx b/website/src/content/docs/plugin-apis/timezone.mdx new file mode 100644 index 00000000..bafe0220 --- /dev/null +++ b/website/src/content/docs/plugin-apis/timezone.mdx @@ -0,0 +1,37 @@ +--- +layout: "layouts/DocLayout.astro" +title: TimeZone +description: Documentation for the TimeZone API for spotube plugins +order: 3 +--- + +The `TimeZone` API provides access to the current time zone of the device running Spotube. This can be useful for plugins that need to display +or handle time-related information based on the user's local time zone. + +## Usage + +To use the `TimeZone` API, you can import the `spotube_plugin` module and access the `TimeZone` class. + +```hetu_script +import "module:spotube_plugin" as spotube + +var TimeZone = spotube.TimeZone +``` + +To get current local time zone for the device, you can use the `getLocalTimeZone` method: + +```hetu_script +TimeZone.getLocalTimeZone().then((timeZone) { + print("Current local time zone: $timeZone") // e.g., "America/New_York" +}) +``` + +To get all available time zones, you can use the `getAvailableTimeZones` method: + +```hetu_script +TimeZone.getAvailableTimeZones().then((timeZones) { + for (var tz in timeZones) { + print("Available time zone: $tz") // e.g., "America/New_York", "Europe/London", etc. + } +}) +``` diff --git a/website/src/content/docs/plugin-apis/webview.mdx b/website/src/content/docs/plugin-apis/webview.mdx new file mode 100644 index 00000000..775e262a --- /dev/null +++ b/website/src/content/docs/plugin-apis/webview.mdx @@ -0,0 +1,75 @@ +--- +layout: "layouts/DocLayout.astro" +title: WebView +description: Documentation for the WebView API for spotube plugins +order: 0 +--- + +The [hetu_spotube_plugin][hetu_spotube_plugin] is a built-in module that plugin developers can use in their plugins. + +```hetu_script +import "module:spotube_plugin" as spotube +``` + +## WebView API + +The WebView API allows plugins to create and manage web views within the Spotube application. + +### Usage + +First, an WebView instance needs to be created with `uri`. + +```hetu_script +import "module:spotube_plugin" as spotube + +let webview = spotube.Webview(uri: "https://example.com") +``` + +To open the webview, you can use the `open` method: + +```hetu_script +webview.open() // returns Future +``` + +To close the webview, you can use the `close` method: + +```hetu_script +webview.close() // returns Future +``` + +### Listening to URL changes + +You can listen to url change events by using the `onUrlRequestStream` method. It's emitted when the URL of the webview changes, +such as when the user navigates to a different page or clicks a link. + +```hetu_script +// Make sure to import the hetu_std and Stream +import "module:hetu_std" as std + +var Stream = std.Stream + +// ... created webview instance and other stuff + +var subscription = webview.onUrlRequestStream().listen((url) { + // Handle the URL change + print("URL changed to: $url") +}) + +// Don't forget to cancel the subscription when it's no longer needed +subscription.cancel() +``` + +### Retrieving cookies + +To get cookies from the webview, you can use the `getCookies` method: + +```hetu_script +webview.getCookies("https://example.com") // returns Future> +``` + +You can find the [`Cookie` class][spotube_plugin_cookie] and all it's methods and properties in the +`hetu_spotube_plugin` module source code + +{/* Links */} +[hetu_spotube_plugin]: https://github.com/KRTirtho/hetu_spotube_plugin +[spotube_plugin_cookie]: https://github.com/KRTirtho/hetu_spotube_plugin/blob/main/lib/assets/hetu/webview.ht