astro-integration-pocketbase 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 pawcode Development
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# astro-integration-pocketbase
+
+<!-- ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/pawcoding/astro-integration-pocketbase/release.yaml?style=flat-square) -->
+
+[![NPM Version](https://img.shields.io/npm/v/astro-integration-pocketbase?style=flat-square)](https://www.npmjs.com/package/astro-integration-pocketbase)
+[![NPM Downloads](https://img.shields.io/npm/dw/astro-integration-pocketbase?style=flat-square)](https://www.npmjs.com/package/astro-integration-pocketbase)
+[![GitHub License](https://img.shields.io/github/license/pawcoding/astro-integration-pocketbase?style=flat-square)](https://github.com/pawcoding/astro-integration-pocketbase/blob/master/LICENSE)
+[![Discord](https://img.shields.io/discord/484669557747875862?style=flat-square&label=Discord)](https://discord.gg/GzgTh4hxrx)
+
+This package provides an Astro toolbar for users of [astro-loader-pocketbase](https://github.com/pawcoding/astro-loader-pocketbase) to view PocketBase data directly in the Astro dev server.
+
+![PocketBase Toolbar](/assets/toolbar.png)
+
+> [!WARNING]
+> This package is still under development.
+> Until the first stable 1.0 release **breaking changes can occur at any time**.
+
+## Basic usage
+
+_For the toolbar to work, you need to have the [`astro-loader-pocketbase`](https://www.npmjs.com/package/astro-loader-pocketbase) package installed and configured in your project._
+
+To use the toolbar, you need to import the `pocketbaseIntegration` function and add it to the `integrations` array in your Astro config file.
+
+```ts
+import { pocketbaseIntegration } from "astro-integration-pocketbase";
+import { defineConfig } from "astro/config";
+
+export default defineConfig({
+  integrations: [
+    pocketbaseIntegration({
+      // Make sure to use the same URL as in your pocketbaseLoader configuration
+      url: "https://<your-pocketbase-url>"
+    })
+  ]
+});
+```
+
+After adding the integration to your Astro config, you can start the dev server and see the PocketBase icon in the toolbar.
+If you click on the icon, you can see the PocketBase entity viewer.
+
+If a loader is found, the viewer will show a refresh button to reload all entries from the loaders.
+
+## Entity viewer
+
+To view the PocketBase entries inside the entity viewer, you need to use `Astro.props` to pass the entries to your page (and thus to the toolbar).
+
+<details>
+  <summary>
+    Example page with PocketBase entries from a collection
+  </summary>
+
+```astro
+---
+import { render, getCollection } from "astro:content";
+import type { CollectionEntry } from "astro:content";
+
+interface Props {
+  entry: CollectionEntry<"<your-collection">
+}
+
+export async function getStaticPaths() {
+  const entries = await getCollection("<your-collection>");
+  return entries.map((entry) => ({
+    params: { id: entry.id },
+    props: { entry },
+  }));
+}
+
+const { entry } = Astro.props;
+const { Content } = await render(entry);
+---
+
+<article>
+  <h1>{entry.data.title}</h1>
+  <Content />
+</article>
+```
+
+</details>
+
+The integration will automatically detect PocketBase entries in the props and display them in the entity viewer.
+
+## All options
+
+| Option | Type     | Required | Description                          |
+| ------ | -------- | -------- | ------------------------------------ |
+| `url`  | `string` | x        | The URL of your PocketBase instance. |

package/index.ts

@@ -0,0 +1,3 @@
+import { pocketbaseIntegration } from "./src/pocketbase-integration";
+
+export { pocketbaseIntegration };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "astro-integration-pocketbase",
+  "version": "0.1.0",
+  "license": "MIT",
+  "author": "Luis Wolf <development@pawcode.de> (https://pawcode.de)",
+  "homepage": "https://github.com/pawcoding/astro-integration-pocketbase",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "src",
+    "index.ts"
+  ],
+  "scripts": {
+    "lint": "npx eslint",
+    "prepare": "husky"
+  },
+  "peerDependencies": {
+    "astro": "^4.0.0 || ^5.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.12.0",
+    "@stylistic/eslint-plugin": "^2.9.0",
+    "@types/node": "^22.7.4",
+    "astro": "^5.0.0-beta.3",
+    "eslint": "^9.12.0",
+    "globals": "^15.10.0",
+    "husky": "^9.1.6",
+    "typescript": "^5.6.2",
+    "typescript-eslint": "^8.8.0"
+  },
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "pocketbase",
+    "withastro"
+  ]
+}

package/src/middleware/index.ts

@@ -0,0 +1,20 @@
+import { defineMiddleware } from "astro/middleware";
+import { isPocketbaseEntry } from "./is-pocketbase-entry";
+
+export const onRequest = defineMiddleware(async (context, next) => {
+  // Look for entities given as props to the page
+  const props = Object.values(context.props);
+  const entities = props.filter(isPocketbaseEntry).map((prop) => prop.data);
+
+  const response = await next();
+  const body = await response.text();
+
+  // Append the entities to the <head>
+  const entitiesJson = JSON.stringify(entities);
+  const newBody = body.replace(
+    "</head>",
+    `<script>window.__astro_entities__ = ${entitiesJson}</script></head>`
+  );
+
+  return new Response(newBody, response);
+});

package/src/middleware/is-pocketbase-entry.ts

@@ -0,0 +1,35 @@
+import { z } from "astro/zod";
+
+/**
+ * Schema for a PocketBase entry created with [astro-loader-pocketbase](https://github.com/pawcoding/astro-loader-pocketbase)
+ */
+const pocketbaseEntrySchema = z.object({
+  id: z.string().length(15),
+  data: z.object({
+    id: z.string().length(15),
+    collectionId: z.string().length(15),
+    collectionName: z.string(),
+    updated: z.optional(z.date()),
+    created: z.optional(z.date())
+  }),
+  digest: z.string().length(16),
+  collection: z.string()
+});
+
+/**
+ * Type for a PocketBase entry created with [astro-loader-pocketbase](https://github.com/pawcoding/astro-loader-pocketbase)
+ */
+export type PocketBaseEntry = z.infer<typeof pocketbaseEntrySchema>;
+
+/**
+ * Checks if the given data is a PocketBase entry.
+ */
+export function isPocketbaseEntry(data: unknown): data is PocketBaseEntry {
+  try {
+    // Try to parse the data with the PocketBase entry schema
+    pocketbaseEntrySchema.parse(data);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/pocketbase-integration.ts

@@ -0,0 +1,67 @@
+import type { AstroIntegration } from "astro";
+import { fileURLToPath } from "node:url";
+
+export function pocketbaseIntegration({
+  url
+}: {
+  url: string;
+}): AstroIntegration {
+  return {
+    name: "pocketbase-integration",
+    hooks: {
+      "astro:config:setup": ({ addDevToolbarApp, addMiddleware, command }) => {
+        // This integration is only available in dev mode
+        if (command !== "dev") {
+          return;
+        }
+
+        // Setup Toolbar
+        addDevToolbarApp({
+          name: "PocketBase",
+          id: `pocketbase-entry`,
+          icon: `<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>PocketBase</title><path fill="currentColor" d="M5.684 12a.632.632 0 0 1-.631-.632V4.421c0-.349.282-.632.631-.632h2.37c.46 0 .889.047 1.287.139.407.084.758.23 1.053.44.303.202.541.475.715.82.173.335.26.75.26 1.246 0 .479-.092.894-.273 1.247a2.373 2.373 0 0 1-.715.869 3.11 3.11 0 0 1-1.053.503c-.398.11-.823.164-1.273.164h-.46a.632.632 0 0 0-.632.632v1.52a.632.632 0 0 1-.632.631Zm1.279-4.888c0 .349.283.632.632.632h.343c1.04 0 1.56-.437 1.56-1.31 0-.428-.135-.73-.404-.907-.26-.176-.645-.264-1.156-.264h-.343a.632.632 0 0 0-.632.631Zm6.3 13.098a.632.632 0 0 1-.631-.631v-6.947a.63.63 0 0 1 .631-.632h2.203c.44 0 .845.034 1.216.1.38.06.708.169.984.328.276.16.492.37.647.63.164.26.246.587.246.982 0 .185-.03.37-.09.554a1.537 1.537 0 0 1-.26.516 1.857 1.857 0 0 1-1.076.7.031.031 0 0 0-.023.03c0 .015.01.028.025.03.591.111 1.04.32 1.346.626.311.31.466.743.466 1.297 0 .42-.082.78-.246 1.083a2.153 2.153 0 0 1-.685.755 3.4 3.4 0 0 1-1.036.441 5.477 5.477 0 0 1-1.268.139zm1.271-5.542c0 .349.283.631.632.631h.21c.465 0 .802-.088 1.009-.264.207-.176.31-.424.31-.743 0-.302-.107-.516-.323-.642-.207-.135-.535-.202-.984-.202h-.222a.632.632 0 0 0-.632.632Zm0 3.463c0 .349.283.631.632.631h.39c1.019 0 1.528-.369 1.528-1.108 0-.36-.125-.621-.376-.78-.241-.16-.625-.24-1.152-.24h-.39a.632.632 0 0 0-.632.632zM1.389 0C.629 0 0 .629 0 1.389V15.03a1.4 1.4 0 0 0 1.389 1.39H8.21a.632.632 0 0 0 .63-.632.632.632 0 0 0-.63-.63H1.389c-.078 0-.125-.05-.125-.128V1.39c0-.078.047-.125.125-.125H15.03c.078 0 .127.047.127.125v6.82a.632.632 0 0 0 .631.63.632.632 0 0 0 .633-.63V1.389A1.4 1.4 0 0 0 15.032 0ZM15.79 7.578a.632.632 0 0 0-.632.633.632.632 0 0 0 .631.63h6.822c.078 0 .125.05.125.128V22.61c0 .078-.047.125-.125.125H8.97c-.077 0-.127-.047-.127-.125v-6.82a.632.632 0 0 0-.631-.63.632.632 0 0 0-.633.63v6.822A1.4 1.4 0 0 0 8.968 24h13.643c.76 0 1.389-.629 1.389-1.389V8.97a1.4 1.4 0 0 0-1.389-1.39Z"/></svg>`,
+          entrypoint: fileURLToPath(new URL("./toolbar", import.meta.url))
+        });
+
+        // Setup middleware
+        addMiddleware({
+          order: "post",
+          entrypoint: fileURLToPath(new URL("./middleware", import.meta.url))
+        });
+      },
+      "astro:server:setup": ({ toolbar, logger, refreshContent }) => {
+        // Setup the listener for the refresh event if a loader is available
+        if (refreshContent) {
+          logger.info("Setting up refresh listener for PocketBase integration");
+          // Listen for the refresh event of the toolbar
+          toolbar.on("astro-integration-pocketbase:refresh", async () => {
+            // Send a loading state to the toolbar
+            toolbar.send("astro-integration-pocketbase:refresh", {
+              loading: true
+            });
+
+            // Refresh content loaded by the PocketBase loader
+            await refreshContent({
+              loaders: ["pocketbase-loader"],
+              // TODO: add context to refresh one or all collections
+              context: {}
+            });
+
+            // Reset the loading state in the toolbar
+            toolbar.send("astro-integration-pocketbase:refresh", {
+              loading: false
+            });
+          });
+        }
+
+        // Send settings to the toolbar on initialization
+        toolbar.onAppInitialized("pocketbase-entry", () => {
+          toolbar.send("astro-integration-pocketbase:settings", {
+            enabled: !!refreshContent,
+            baseUrl: url
+          });
+        });
+      }
+    }
+  };
+}

package/src/toolbar/dom/create-entity.ts

@@ -0,0 +1,42 @@
+import type { DevToolbarCard } from "astro/runtime/client/dev-toolbar/ui-library/card.js";
+import type { Entity } from "../types/entity";
+
+/**
+ * Creates a card for an entity.
+ */
+export function createEntity(data: Entity, baseUrl?: string): DevToolbarCard {
+  // Create the main card
+  const main = document.createElement("astro-dev-toolbar-card");
+
+  // Create the main content container
+  const content = document.createElement("div");
+  content.style.position = "relative";
+  main.appendChild(content);
+
+  // Add the "View in PocketBase" button
+  if (baseUrl) {
+    const url = `${baseUrl}/_/#/collections?collectionId=${data.collectionId}&recordId=${data.id}`;
+
+    const viewInPocketbase = document.createElement("astro-dev-toolbar-button");
+    viewInPocketbase.size = "small";
+    viewInPocketbase.buttonStyle = "purple";
+    viewInPocketbase.textContent = "View in PocketBase";
+    viewInPocketbase.style.position = "absolute";
+    viewInPocketbase.style.top = "0";
+    viewInPocketbase.style.right = "0";
+    viewInPocketbase.addEventListener("click", () => {
+      window.open(url, "_blank");
+    });
+    content.appendChild(viewInPocketbase);
+  }
+
+  // Add the entity data
+  const entity = document.createElement("pre");
+  entity.style.margin = "0";
+  entity.style.overflow = "auto";
+  entity.style.height = "300px";
+  entity.textContent = JSON.stringify(data, null, 2);
+  content.appendChild(entity);
+
+  return main;
+}

package/src/toolbar/dom/create-header.ts

@@ -0,0 +1,43 @@
+import type { ToolbarServerHelpers } from "astro";
+import type { DevToolbarButton } from "astro/runtime/client/dev-toolbar/ui-library/button.js";
+import { default as packageJson } from "../../../package.json";
+
+/**
+ * Creates the header for the PocketBase toolbar.
+ */
+export function createHeader(
+  server: ToolbarServerHelpers
+): [HTMLElement, DevToolbarButton] {
+  // Create the header
+  const header = document.createElement("header");
+  header.style.display = "grid";
+  header.style.gap = "0.25rem";
+  header.style.gridTemplateColumns = "auto auto 1fr";
+
+  // Create the title
+  const title = document.createElement("h3");
+  title.style.marginTop = "0.25rem";
+  title.textContent = "PocketBase";
+  header.appendChild(title);
+
+  // Create the version badge
+  const version = document.createElement("astro-dev-toolbar-badge");
+  version.textContent = packageJson.version;
+  version.badgeStyle = "yellow";
+  header.appendChild(version);
+
+  // Create the refresh button
+  const refresh = document.createElement("astro-dev-toolbar-button");
+  refresh.size = "small";
+  refresh.buttonStyle = "green";
+  refresh.style.marginLeft = "auto";
+  refresh.textContent = "Refresh content";
+  // The refresh button is hidden by default
+  refresh.style.display = "none";
+  refresh.addEventListener("click", () => {
+    server.send("astro-integration-pocketbase:refresh", true);
+  });
+  header.appendChild(refresh);
+
+  return [header, refresh];
+}

package/src/toolbar/dom/create-placeholder.ts

@@ -0,0 +1,23 @@
+import type { DevToolbarCard } from "astro/runtime/client/dev-toolbar/ui-library/card.js";
+
+/**
+ * Creates a placeholder card.
+ */
+export function createPlaceholder(): DevToolbarCard {
+  // Create the main card
+  const main = document.createElement("astro-dev-toolbar-card");
+
+  // Create the main content container
+  const content = document.createElement("div");
+  content.style.display = "flex";
+  content.style.alignItems = "center";
+  content.style.justifyContent = "center";
+  main.appendChild(content);
+
+  // Add the placeholder text
+  const placeholder = document.createElement("span");
+  placeholder.textContent = "Here you will see the raw content of an entity";
+  content.appendChild(placeholder);
+
+  return main;
+}

package/src/toolbar/dom/index.ts

@@ -0,0 +1,3 @@
+export * from "./create-entity";
+export * from "./create-header";
+export * from "./create-placeholder";

package/src/toolbar/index.ts

@@ -0,0 +1,6 @@
+import { defineToolbarApp } from "astro/toolbar";
+import { initToolbar } from "./init-toolbar";
+
+export default defineToolbarApp({
+  init: initToolbar
+});

package/src/toolbar/init-toolbar.ts

@@ -0,0 +1,141 @@
+import type {
+  ToolbarAppEventTarget,
+  ToolbarServerHelpers
+} from "astro/runtime/client/dev-toolbar/helpers.js";
+import { createEntity, createHeader, createPlaceholder } from "./dom/";
+import { listenToNavigation } from "./page-navigation-listener";
+import type { Entity } from "./types/entity";
+
+declare global {
+  interface Window {
+    __astro_entities__?: Array<Entity>;
+  }
+}
+
+/**
+ * Initializes the PocketBase toolbar.
+ */
+export async function initToolbar(
+  canvas: ShadowRoot,
+  app: ToolbarAppEventTarget,
+  server: ToolbarServerHelpers
+): Promise<void> {
+  // Base url of the PocketBase instance
+  let pbUrl: string | undefined = undefined;
+
+  const container = document.createElement("astro-dev-toolbar-window");
+
+  const [header, refresh] = createHeader(server);
+  container.appendChild(header);
+
+  // Container for the main content
+  const contentContainer = document.createElement("div");
+  container.appendChild(contentContainer);
+
+  const placeholder = createPlaceholder();
+  contentContainer.appendChild(placeholder);
+
+  app.onToggled(({ state }) => {
+    // Clear the container
+    contentContainer.innerHTML = "";
+
+    if (!state) {
+      // Clear the dev-window
+      canvas.innerHTML = "";
+      return;
+    }
+
+    // Append the dev-window
+    canvas.appendChild(container);
+
+    // Check if entities are present
+    const entities = window.__astro_entities__;
+    if (!entities || entities.length === 0) {
+      // No entities to display, show a placeholder
+      contentContainer.appendChild(createPlaceholder());
+      return;
+    }
+
+    // Display the information about the entities
+    for (const entity of entities) {
+      contentContainer.appendChild(createEntity(entity, pbUrl));
+    }
+  });
+
+  // Update the toolbar placement based on the user's preference
+  function updateToolbarPlacement(
+    placement: "bottom-left" | "bottom-right" | "bottom-center"
+  ) {
+    if (placement === "bottom-left") {
+      container.style.left = "16px";
+      container.style.right = "unset";
+      container.style.transform = "translateX(0)";
+    } else if (placement === "bottom-right") {
+      container.style.left = "unset";
+      container.style.right = "16px";
+      container.style.transform = "translateX(0)";
+    } else {
+      container.style.left = "50%";
+      container.style.right = "unset";
+      container.style.transform = "translateX(-50%)";
+    }
+  }
+
+  // Read the initial toolbar placement from local storage
+  // This is a workaround since the initial toolbar placement is not available via any API
+  const settings = localStorage.getItem("astro:dev-toolbar:settings");
+  if (settings) {
+    const { placement } = JSON.parse(settings);
+    updateToolbarPlacement(placement);
+  }
+
+  // Listen for toolbar placement updates
+  app.onToolbarPlacementUpdated(({ placement }) => {
+    updateToolbarPlacement(placement);
+  });
+
+  server.on(
+    "astro-integration-pocketbase:settings",
+    ({ enabled, baseUrl }: { enabled: boolean; baseUrl: string }) => {
+      // Show the refresh button if a loader is available
+      if (enabled) {
+        refresh.style.display = "unset";
+      }
+
+      // Store the base URL for later use
+      pbUrl = baseUrl;
+    }
+  );
+
+  server.on(
+    "astro-integration-pocketbase:refresh",
+    ({ loading }: { loading?: boolean }) => {
+      // Show loading state while refreshing content
+      if (loading) {
+        refresh.textContent = "Refreshing content...";
+        refresh.buttonStyle = "gray";
+        refresh.style.pointerEvents = "none";
+      } else {
+        refresh.textContent = "Refresh content";
+        refresh.buttonStyle = "green";
+        refresh.style.pointerEvents = "unset";
+      }
+    }
+  );
+
+  // Toggle the notification based on the presence of entities
+  listenToNavigation(() => {
+    // Check if entities are present
+    const entities = window.__astro_entities__;
+    if (!entities || entities.length === 0) {
+      app.toggleNotification({ state: false });
+
+      // Hide the toolbar if no entities are present
+      app.toggleState({ state: false });
+      return;
+    }
+
+    // Show the notification
+    app.toggleNotification({ state: true, level: "info" });
+  });
+}

package/src/toolbar/page-navigation-listener.ts

@@ -0,0 +1,14 @@
+/**
+ * Execute a callback whenever the user navigates to a new page.
+ */
+export function listenToNavigation(callback: () => void): void {
+  // We trigger the callback immediately to ensure the toolbar is in sync with the current page.
+  // If no client-side navigation is done, this is the only time the callback will be triggered.
+  // Fortunately, this scrip will be re-executed on every page load.
+  callback();
+
+  // If client-side navigation is done (ViewTransitions / ClientRouter), we listen for page-load events.
+  document.addEventListener("astro:page-load", () => {
+    callback();
+  });
+}

package/src/toolbar/types/entity.ts

@@ -0,0 +1,7 @@
+/**
+ * Minimal entity interface
+ */
+export interface Entity {
+  id: string;
+  collectionId: string;
+}