kitty/spotube
1
0
Fork 0
mirror of https://github.com/KRTirtho/spotube.git synced 2025-09-13 07:55:18 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: add plugin API docs

Browse Source
This commit is contained in:
Kingkor Roy Tirtho 2025-08-14 21:21:09 +06:00
parent 0e34057794
commit 30fd4acf37
7 changed files with 292 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
website/src/components/navigation/DocSideBar.astro
View File

@ -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

5
website/src/components/navigation/TopBar.astro
View File

@ -4,10 +4,11 @@ import { FaGithub } from "react-icons/fa6";
import SidebarButton from "./sidebar-button";
const pathname = Astro.url.pathname;
console.log("pathname:", pathname);
---
<header class="flex justify-between items-center px-4 bg-surface">
<header
class="flex justify-between items-center p-4 top-0 fixed w-full z-10 backdrop-blur-md backdrop-saturate-150"
>
<div class="flex items-center justify-between w-full">
<div class="flex items-center gap-2">
<SidebarButton client:only />

2
website/src/components/navigation/sidebar-button.tsx
View File

@ -13,7 +13,7 @@ export default function SidebarButton() {
return <>
<div className={
`fixed h-screen w-72 bg-surface-100 dark:bg-surface-900 top-0 left-0 bg-surface z-50 transition-all duration-300 ${isOpen ? "" : "-translate-x-full"}`
`fixed h-screen w-72 bg-surface-100 dark:bg-surface-900 top-0 left-0 bg-surface z-50 transition-all duration-300 ${isOpen ? "" : "-translate-x-full opacity-0"}`
}
ref={ref}
>

72
website/src/content/docs/plugin-apis/forms.mdx Normal file
View File

@ -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"
}
]
```

103
website/src/content/docs/plugin-apis/localstorage.mdx Normal file
View File

@ -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

37
website/src/content/docs/plugin-apis/timezone.mdx Normal file
View File

@ -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.
}
})
```

75
website/src/content/docs/plugin-apis/webview.mdx Normal file
View File

@ -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<void>
```
To close the webview, you can use the `close` method:
```hetu_script
webview.close() // returns Future<void>
```
### 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<List<Cookie>>
```
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