ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
feat(sdk): a second widget surface — types users place, not just slots
Juan Denis92e0750262f1
diff --git a/backend/app/api/plugins.py b/backend/app/api/plugins.pyindex 229246ba..7c6d6171 100644--- a/backend/app/api/plugins.py+++ b/backend/app/api/plugins.py@@ -487,6 +487,8 @@ def get_manifest_spec():'page_titles': {'type': 'object', 'description': 'Map of route path → document title.'},'command_palette': {'type': 'array', 'description': '{label, path, category, keywords}.'},'widgets': {'type': 'array', 'description': '{slot, component}. slot=global renders globally inside DashboardLayout.'},+ 'dashboard_widgets': {'type': 'array',+ 'description': 'Placeable dashboard widget types: {id, name, component, icon?, category?, description?, w?, h?, min?, default_cfg?}. Unlike widgets (fixed host slot), these appear in the dashboard widget library and the user positions, resizes and configures instances of them.'},'layouts': {'type': 'array','description': 'Custom layout components: {id, component}. The component must render <Outlet/> somewhere; it wraps every route that references its id. Built-in layouts (padded, full, bare) are reserved.'},},diff --git a/backend/app/services/contribution_service.py b/backend/app/services/contribution_service.pyindex a10a241d..8eec9d5a 100644--- a/backend/app/services/contribution_service.py+++ b/backend/app/services/contribution_service.py@@ -9,10 +9,21 @@ A plugin manifest may declare a `contributions` block with any subset of:"page_titles": { "/some-path": "Title" },"command_palette":[{ label, path, category, keywords }],"widgets": [{ slot, component }],+ "dashboard_widgets": [{ id, name, component, icon?, category?,+ description?, w?, h?, min?, default_cfg? }],"layouts": [{ id, component }],"tabs": [{ group, to, label, icon?, end?, order? }]}+`widgets` and `dashboard_widgets` are different surfaces and are easy to+confuse. A `widgets` entry mounts a component at a FIXED host slot+(`<PluginSlot name="dashboard.top" />`) — the host decides where it goes and+the user cannot move it. A `dashboard_widgets` entry registers a placeable+widget TYPE: it appears in the dashboard's widget library, and the user adds,+positions, resizes and configures instances of it on a dashboard board. Use+`widgets` to enrich an existing page, `dashboard_widgets` to offer a new+building block.+A `tabs` entry adds a tab to a core-owned TabGroupLayout group; `group` is thecore group id (== the sidebar item id: files | servers | monitoring). Pair itwith a route contribution carrying the same `group` so the page renders INSIDE@@ -99,6 +110,7 @@ def get_active_contributions():page_titles = {}command_palette = []widgets = []+ dashboard_widgets = []layouts = []tabs = []# AI assistant contributions: per-route suggested prompts + custom@@ -114,6 +126,7 @@ def get_active_contributions():routes.extend(_tag(contrib.get('routes'), p.slug))command_palette.extend(_tag(contrib.get('command_palette'), p.slug))widgets.extend(_tag(contrib.get('widgets'), p.slug))+ dashboard_widgets.extend(_tag(contrib.get('dashboard_widgets'), p.slug))layouts.extend(_tag(contrib.get('layouts'), p.slug))tabs.extend(_tag(contrib.get('tabs'), p.slug))@@ -134,6 +147,7 @@ def get_active_contributions():'page_titles': page_titles,'command_palette': command_palette,'widgets': widgets,+ 'dashboard_widgets': dashboard_widgets,'layouts': layouts,'tabs': tabs,'ai': ai,diff --git a/backend/app/services/plugin_service.py b/backend/app/services/plugin_service.pyindex 7a0ad587..23492468 100644--- a/backend/app/services/plugin_service.py+++ b/backend/app/services/plugin_service.py@@ -343,6 +343,7 @@ _REQUIRED_CONTRIB_KEYS = {'tabs': ('group', 'to', 'label'),'command_palette': ('label', 'path'),'widgets': ('slot', 'component'),+ 'dashboard_widgets': ('id', 'name', 'component'),'layouts': ('id', 'component'),}diff --git a/backend/app/utils/sdk.py b/backend/app/utils/sdk.pyindex edd401fc..43c7b506 100644--- a/backend/app/utils/sdk.py+++ b/backend/app/utils/sdk.py@@ -27,7 +27,7 @@ import refrom app.utils.version import compare_versions# Keep in lock-step with frontend/src/plugins/sdk/index.js `SDK_VERSION`.-SDK_VERSION = '1.0.0'+SDK_VERSION = '1.1.0'def _version_tuple(v):diff --git a/backend/tests/test_plugins_pipeline.py b/backend/tests/test_plugins_pipeline.pyindex dd5ddd75..2984c070 100644--- a/backend/tests/test_plugins_pipeline.py+++ b/backend/tests/test_plugins_pipeline.py@@ -61,6 +61,12 @@ def _write_builtin(builtin_dir, slug='serverkit-demo', version='1.0.0',# TabGroupLayout group, paired with the group route above.'tabs': [{'group': 'files', 'to': '/demo-tab', 'label': 'Demo Tab','icon': '<circle cx="12" cy="12" r="8"/>'}],+ # Placeable dashboard widget type (plan 62): shows up in the+ # dashboard widget library, not at a fixed host slot.+ 'dashboard_widgets': [{'id': 'demo-widget', 'name': 'Demo Widget',+ 'component': 'DemoWidget', 'category': 'Utility',+ 'w': 3, 'h': 2, 'min': [2, 2],+ 'default_cfg': {'limit': 5}}],},}(folder / 'plugin.json').write_text(json.dumps(manifest), encoding='utf-8')@@ -188,7 +194,7 @@ def test_contributions_endpoint_envelope(app, client, auth_headers, plugin_dirs)# The envelope always carries every key.for key in ('nav', 'routes', 'page_titles', 'command_palette', 'widgets',- 'layouts', 'tabs', 'ai'):+ 'dashboard_widgets', 'layouts', 'tabs', 'ai'):assert key in data# Contributions are tagged with the source plugin slug.@@ -205,6 +211,13 @@ def test_contributions_endpoint_envelope(app, client, auth_headers, plugin_dirs)assert any(r.get('plugin') == 'serverkit-demo' and r.get('group') == 'files'and r.get('component') == 'DemoTabPage' for r in data['routes'])+ # Placeable dashboard widget types travel on their own key, tagged with the+ # slug, and never leak into the fixed-slot `widgets` surface.+ assert any(w.get('plugin') == 'serverkit-demo' and w.get('id') == 'demo-widget'+ and w.get('component') == 'DemoWidget'+ for w in data['dashboard_widgets'])+ assert not any(w.get('id') == 'demo-widget' for w in data['widgets'])+def test_disabled_plugin_drops_from_contributions(app, client, auth_headers, plugin_dirs):_write_builtin(plugin_dirs['builtin'])diff --git a/docs/EXTENSIONS.md b/docs/EXTENSIONS.mdindex a646f09f..b323d138 100644--- a/docs/EXTENSIONS.md+++ b/docs/EXTENSIONS.md@@ -106,6 +106,11 @@ tagged at runtime with its source `plugin` slug so the frontend can resolve{ "label": "Git", "path": "/git", "category": "Pages", "keywords": "repos deploy" }],"widgets": [ { "slot": "dashboard.top", "component": "GitStatusWidget" } ],+ "dashboard_widgets": [+ { "id": "git-activity", "name": "Git activity", "component": "GitActivityWidget",+ "category": "Operations", "description": "Recent pushes across repositories",+ "w": 4, "h": 3, "min": [3, 2], "default_cfg": { "limit": 6 } }+ ],"layouts": [ { "id": "my-fullscreen", "component": "MyLayout" } ],"tabs": [{ "group": "files", "to": "/ftp", "label": "FTP Server", "icon": "<rect …/>" }@@ -123,7 +128,8 @@ tagged at runtime with its source `plugin` slug so the frontend can resolve| `routes` | `{path,component,layout?,group?}` | `component` = a named export of the plugin's `index.{js,jsx}`. `layout`: `padded` (default) / `full` / `bare` / a custom layout id. `group` nests the route inside a core tab group instead — see [Tab-group contributions](#tab-group-contributions). || `page_titles` | `{ "/path": "Title" }` | Sets `document.title`. || `command_palette` | `{label,path,category,keywords}` | `category` defaults to `Extensions`. |-| `widgets` | `{slot,component}` | Slots: `global` (renders inside DashboardLayout), plus the enrich-core slots (`dashboard.top`, `service.detail.tab`, `domain.drawer.panel`). |+| `widgets` | `{slot,component}` | Slots: `global` (renders inside DashboardLayout), plus the enrich-core slots (`dashboard.top`, `service.detail.tab`, `domain.drawer.panel`). Fixed position — the host decides where it renders. |+| `dashboard_widgets` | `{id,name,component,icon?,category?,description?,w?,h?,min?,default_cfg?}` | Registers a **placeable** widget type in the dashboard widget library. The user adds, moves, resizes and configures instances on their own boards. `category`: Metrics/Inventory/Operations/Utility (defaults to `Extensions`). `w`/`h` = default span in a 12-column grid; `min` = `[minW,minH]`. The component receives `{ widget, ctx }` — see [Dashboard widgets](#dashboard-widgets). || `layouts` | `{id,component}` | Custom wrappers; the component must render `<Outlet/>`. Built-in ids `padded`/`full`/`bare` are reserved. || `tabs` | `{group,to,label,icon?,end?,order?}` | Adds a tab to a core-owned tab group. `group` = the group id (`files` / `servers` / `monitoring`). See [Tab-group contributions](#tab-group-contributions). || `ai` | `{suggested_prompts,tool_renderers}` | See [AI](#extending-the-ai-assistant). |@@ -136,6 +142,55 @@ tagged at runtime with its source `plugin` slug so the frontend can resolvefullscreen authenticated pages.- `<custom-id>` — wrapped in a `layouts`-contributed component.+### Dashboard widgets++The dashboard is a 12-column grid of user-placed widgets. `dashboard_widgets`+registers a widget **type** so it appears in the widget library and users can+drop instances onto their own boards.++Don't confuse the two widget surfaces:++| | `widgets` | `dashboard_widgets` |+|---|---|---|+| Where it renders | a fixed host slot you name | anywhere the user drags it |+| Who decides position | the host | the user |+| Instances | one per slot | many, each independently configured |+| Use it to | enrich an existing page | offer a new building block |++```jsonc+"dashboard_widgets": [+ { "id": "git-activity",+ "name": "Git activity",+ "component": "GitActivityWidget", // named export of your index module+ "category": "Operations", // Metrics|Inventory|Operations|Utility+ "description": "Recent pushes across repositories",+ "w": 4, "h": 3, "min": [3, 2], // default span / minimum span+ "default_cfg": { "limit": 6 } }+]+```++Ids are namespaced by the panel as `<plugin-slug>:<id>`, so two extensions can+both ship a `activity` widget without colliding.++Your component receives two props:++```jsx+export function GitActivityWidget({ widget, ctx }) {+ // widget.cfg — this instance's config, seeded from default_cfg+ // widget.w / widget.h — its current span, if you want to adapt density+ // ctx.range — '1h' | '6h' | '24h' | '7d' | '30d' (the board's time range)+ // ctx.tick — increments on each refresh; put it in your effect deps+ // ctx.serverVar — the board's selected server ('local' or a server id)+ // ctx.isAdmin, ctx.navigate+ return <div className="skw-list">…</div>;+}+```++Render into the space you're given: the frame's header, menu and resize handle+are the host's. A widget that throws is caught and replaced with an error tile+rather than taking the board down, but handle your own loading and empty states+— every core widget does.+### Tab-group contributionsSome core surfaces are **tab groups** (one shared `PageTopbar` + routed tabs,diff --git a/frontend/src/plugins/contributions.js b/frontend/src/plugins/contributions.jsindex ea8d8ac7..52e243b7 100644--- a/frontend/src/plugins/contributions.js+++ b/frontend/src/plugins/contributions.js@@ -78,6 +78,13 @@ const EMPTY = {page_titles: {},command_palette: [],widgets: [],+ // Placeable dashboard widget TYPES: { id, name, component, icon?,+ // category?, description?, w?, h?, min?, default_cfg? }. Distinct from+ // `widgets` above, which mounts a component at a fixed host slot. These+ // show up in the dashboard widget library and the user positions, sizes+ // and configures instances of them. Consumed by+ // components/dashboard/widgets/registry.js via useWidgetTypes().+ dashboard_widgets: [],layouts: [],// Tabs contributed into core-owned TabGroupLayout groups (#43):// { group, to, label, icon?, end?, order? }. `group` is the core group id@@ -118,6 +125,7 @@ function getBuildTimeContributions() {const page_titles = {};const command_palette = [];const widgets = [];+ const dashboard_widgets = [];const layouts = [];const tabs = [];const ai = { suggested_prompts: [], tool_renderers: [] };@@ -134,6 +142,7 @@ function getBuildTimeContributions() {routes.push(...tagItems(contrib.routes, slug));command_palette.push(...tagItems(contrib.command_palette, slug));widgets.push(...tagItems(contrib.widgets, slug));+ dashboard_widgets.push(...tagItems(contrib.dashboard_widgets, slug));layouts.push(...tagItems(contrib.layouts, slug));tabs.push(...tagItems(contrib.tabs, slug));@@ -153,6 +162,7 @@ function getBuildTimeContributions() {page_titles,command_palette,widgets,+ dashboard_widgets,layouts,tabs,ai,diff --git a/frontend/src/plugins/sdk/index.js b/frontend/src/plugins/sdk/index.jsindex 39a31316..bf433e15 100644--- a/frontend/src/plugins/sdk/index.js+++ b/frontend/src/plugins/sdk/index.js@@ -38,7 +38,7 @@// GET /api/v1/plugins/contributions. The backend mirror lives in// backend/app/utils/sdk.py — keep the two in lock-step (asserted by// backend/tests/test_sdk_contract.py).-export const SDK_VERSION = '1.0.0';+export const SDK_VERSION = '1.1.0';export { api, default as defaultApi } from '../../services/api';