@tinacms/astro 0.0.1 → 0.3.0

package/src/data.test-d.ts

@@ -0,0 +1,53 @@
+import { describe, expectTypeOf, it } from 'vitest';
+import type { QueryResult, RequestOptions } from './data';
+import { requestWithMetadata } from './data';
+
+interface Post {
+  title: string;
+  body: string;
+}
+
+// requestWithMetadata is the one wrapper every Astro page calls around
+// client.queries.<name>(). A regression that widened TData to `unknown`
+// would pass every runtime test, so the guarantee has to be type-level.
+
+describe('requestWithMetadata', () => {
+  it('threads the query data type through to QueryResult', async () => {
+    const result = await requestWithMetadata(
+      Promise.resolve({
+        data: { title: 't', body: 'b' } satisfies Post,
+        query: 'query Post { ... }',
+        variables: {},
+      })
+    );
+    expectTypeOf(result).toEqualTypeOf<QueryResult<Post>>();
+    expectTypeOf(result.data).toEqualTypeOf<Post>();
+  });
+
+  it('does not widen TData when given an explicit type argument', () => {
+    expectTypeOf<
+      Awaited<ReturnType<typeof requestWithMetadata<Post>>>
+    >().toEqualTypeOf<QueryResult<Post>>();
+  });
+
+  it('accepts a bare (non-promise) client result', () => {
+    expectTypeOf(requestWithMetadata).toBeCallableWith({
+      data: { title: 't', body: 'b' } satisfies Post,
+      query: 'q',
+      variables: {},
+    });
+  });
+
+  it('accepts null / undefined sources (static build, no client scope)', () => {
+    expectTypeOf(requestWithMetadata).toBeCallableWith(null);
+    expectTypeOf(requestWithMetadata).toBeCallableWith(undefined);
+  });
+});
+
+describe('RequestOptions', () => {
+  it('priority is the literal "primary" or absent', () => {
+    expectTypeOf<RequestOptions['priority']>().toEqualTypeOf<
+      'primary' | undefined
+    >();
+  });
+});

package/src/data.ts

@@ -0,0 +1,73 @@
+import { addMetadata, hashFromQuery } from '@tinacms/bridge/metadata';
+import { readOverlay } from '@tinacms/bridge/preview';
+import { recordForm } from './internal/forms-store';
+import { requestStore } from './internal/request-context';
+
+export interface QueryResult<TData> {
+  data: TData;
+  query: string;
+  variables: Record<string, unknown>;
+  id: string;
+}
+
+type ClientResult<TData> =
+  | {
+      data: TData;
+      query: string;
+      variables: Record<string, unknown>;
+    }
+  | null
+  | undefined;
+
+export interface RequestOptions {
+  /** Mark the page's own document so the admin opens it on load instead
+   *  of a layout-level global. Mirrors `useTina`'s
+   *  `experimental___selectFormByFormId`. */
+  priority?: 'primary';
+}
+
+export async function requestWithMetadata<TData>(
+  source: ClientResult<TData> | Promise<ClientResult<TData>>,
+  options?: RequestOptions
+): Promise<QueryResult<TData>> {
+  let result: ClientResult<TData> = null;
+  try {
+    result = (await source) ?? null;
+  } catch (error) {
+    // In edit mode a doc the editor is creating won't exist yet; the
+    // bridge will populate via overlay. Don't crash the render.
+    console.warn('[@tinacms/astro] client query failed', error);
+  }
+
+  const query = result?.query ?? '';
+  const variables = result?.variables ?? {};
+  const id = hashFromQuery(JSON.stringify({ query, variables }));
+  const data = (result?.data ?? {}) as TData;
+
+  const request = requestStore.getStore();
+  let resolvedData: TData = data;
+  if (request) {
+    const overlay = await readOverlay<TData>(request, id);
+    if (overlay !== undefined) {
+      resolvedData = overlay;
+    }
+  }
+
+  const enriched = {
+    data: addMetadata(id, resolvedData) as TData,
+    query,
+    variables,
+    id,
+  };
+
+  // No-op outside a request scope (static builds).
+  recordForm({
+    id,
+    query,
+    variables,
+    data: enriched.data as unknown as object,
+    priority: options?.priority,
+  });
+
+  return enriched;
+}

package/src/experimental.ts

@@ -0,0 +1,14 @@
+/**
+ * Experimental surface area. Anything here may change in a minor or
+ * patch release — opt in only when the underlying tradeoff is worth
+ * it for your project.
+ *
+ * `experimental_createIslandRoute` builds on Astro's
+ * `experimental_AstroContainer`, which Astro itself flags as unstable;
+ * this re-export inherits the same caveat.
+ */
+export {
+  experimental_createIslandRoute,
+  type IslandConfig,
+  type IslandRegistry,
+} from './island-route';

package/src/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Runtime entry for the package's `.` subpath. Astro consumers resolve
+ * through the `astro` export condition straight to `src/TinaMarkdown.astro`
+ * — they get the real component as the default export plus the named
+ * helpers re-exported from the .astro frontmatter.
+ *
+ * This file is the fallback for any tool that *doesn't* understand the
+ * `astro` condition (TypeScript types, plain Node ESM resolution). It
+ * exposes the named runtime helpers and a placeholder default that
+ * throws with a clear redirect if someone reaches it.
+ */
+import type { AstroComponentFactory } from 'astro/runtime/server/index.js';
+import type { CustomComponentsMap, TinaRichTextContent } from './types';
+
+export { requestWithMetadata, type QueryResult } from './data';
+export { tinaField } from './tina-field';
+export type {
+  AstroComponent,
+  CustomComponentsMap,
+  MdxElement,
+  TextElement,
+  TinaRichTextContent,
+  TinaRichTextNode,
+  TinaRichTextRoot,
+} from './types';
+
+/**
+ * Typed shape of `<TinaMarkdown content={...} components={...} />` for tools
+ * that resolve through the `types` / `default` export condition rather than
+ * the `astro` condition. The actual component is `src/TinaMarkdown.astro`;
+ * this placeholder throws if invoked because the only legitimate caller is
+ * Astro's component pipeline, which reaches the .astro file directly.
+ *
+ * The intersection of `AstroComponentFactory` (Astro's component-validity
+ * check) and a typed prop signature (TinaMarkdown's actual API) gives the
+ * Astro language server enough shape to both recognise this as a renderable
+ * component AND offer prop completions / type errors at the call site.
+ */
+type TinaMarkdownComponent = AstroComponentFactory & {
+  (props: {
+    content: TinaRichTextContent;
+    components?: CustomComponentsMap;
+  }): unknown;
+};
+
+const TinaMarkdownPlaceholder = (() => {
+  throw new Error(
+    "[@tinacms/astro] TinaMarkdown must be loaded through Astro's pipeline. " +
+      'Add `tina()` from `@tinacms/astro/integration` to your astro.config integrations, ' +
+      'or import directly from `@tinacms/astro/TinaMarkdown.astro`.'
+  );
+}) as unknown as TinaMarkdownComponent;
+
+export default TinaMarkdownPlaceholder;

package/src/integration.ts

@@ -0,0 +1,94 @@
+import { copyFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { AstroIntegration, AstroIntegrationLogger } from 'astro';
+import type { Plugin as VitePlugin } from 'vite';
+
+export interface TinaIntegrationOptions {
+  middlewareOrder?: 'pre' | 'post';
+}
+
+/** Where the injected bridge bootstrap imports the bridge bundle from. */
+const BRIDGE_ROUTE = '/admin/bridge.js';
+
+export default function tina(
+  options: TinaIntegrationOptions = {}
+): AstroIntegration {
+  const { middlewareOrder = 'pre' } = options;
+  // Resolved client output dir, captured at config:done and consumed at
+  // build:done (only then is the final output location known).
+  let clientDir: URL | undefined;
+
+  return {
+    name: '@tinacms/astro',
+    hooks: {
+      'astro:config:setup': ({ addMiddleware, updateConfig }) => {
+        addMiddleware({
+          entrypoint: '@tinacms/astro/middleware',
+          order: middlewareOrder,
+        });
+        // Dev: serve the bridge straight from the package rather than writing
+        // it into the user's source tree — config-time writes churn
+        // public/admin on every `astro dev`/`astro build`, break on read-only
+        // or sandboxed filesystems, and can race `tinacms build`.
+        updateConfig({ vite: { plugins: [bridgeDevPlugin()] } });
+      },
+      'astro:config:done': ({ config }) => {
+        clientDir = config.build.client;
+      },
+      'astro:build:done': ({ logger }) => {
+        // Build: emit the bridge next to the admin SPA in the *output* tree.
+        // `build.client` is where `public/` is copied to and what every
+        // adapter serves statically, so the bridge ships as a static asset
+        // (some adapters won't emit injected on-demand routes — e.g.
+        // @astrojs/vercel in static mode) without touching the source tree.
+        if (!clientDir) return;
+        emitBridgeAsset(fileURLToPath(new URL('admin/', clientDir)), logger);
+      },
+    },
+  };
+}
+
+function resolveBridge(): string {
+  return createRequire(import.meta.url).resolve('@tinacms/bridge');
+}
+
+// Dev-only Vite plugin that answers `/admin/bridge.js` from the installed
+// bridge package. The bridge never varies per request, so a single readFile
+// per request is fine and nothing is persisted to disk.
+function bridgeDevPlugin(): VitePlugin {
+  return {
+    name: '@tinacms/astro:bridge-dev',
+    apply: 'serve',
+    configureServer(server) {
+      server.middlewares.use((req, res, next) => {
+        const path = (req.url || '').split('?')[0];
+        if (path !== BRIDGE_ROUTE) {
+          next();
+          return;
+        }
+        try {
+          const body = readFileSync(resolveBridge());
+          res.setHeader('Content-Type', 'text/javascript');
+          res.setHeader('Cache-Control', 'no-cache');
+          res.end(body);
+        } catch (error) {
+          res.statusCode = 500;
+          res.end(`/* @tinacms/astro: bridge unavailable: ${error} */`);
+        }
+      });
+    },
+  };
+}
+
+function emitBridgeAsset(adminDir: string, logger: AstroIntegrationLogger) {
+  try {
+    mkdirSync(adminDir, { recursive: true });
+    copyFileSync(resolveBridge(), join(adminDir, 'bridge.js'));
+  } catch (error) {
+    logger.warn(
+      `could not emit admin/bridge.js — visual editing will not load: ${error}`
+    );
+  }
+}

package/src/internal/admin-origin.ts

@@ -0,0 +1,19 @@
+/**
+ * Resolve `PUBLIC_TINA_ADMIN_ORIGIN` (comma-separated allowed) from
+ * Astro's `import.meta.env`. Returns `null` when unset — the bridge then
+ * falls back to `window.location.origin`.
+ */
+export function adminOrigins(): string[] | null {
+  const env = (
+    import.meta as ImportMeta & {
+      env?: Record<string, string | undefined>;
+    }
+  ).env;
+  const raw = env?.PUBLIC_TINA_ADMIN_ORIGIN;
+  if (!raw) return null;
+  const origins = raw
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+  return origins.length > 0 ? origins : null;
+}

package/src/internal/escape.ts

@@ -0,0 +1,15 @@
+/**
+ * HTML attribute escape for double-quoted attributes. `&` is escaped first
+ * so the subsequent replacements don't double-encode existing entities.
+ * Adequate for the shapes we emit server-side — `data-tina-form` payloads
+ * and `data-tina-island` marker paths — neither of which is parsed as
+ * HTML downstream.
+ */
+export function escapeAttr(s: string): string {
+  return s
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}

package/src/internal/forms-store.ts

@@ -0,0 +1,50 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { escapeAttr } from './escape';
+
+export interface CollectedForm {
+  id: string;
+  query: string;
+  variables: object;
+  data: object;
+  priority?: 'primary';
+}
+
+// Symbol slot on globalThis so bundle copies (esbuild inlines this module
+// into each entry that imports it) share one ALS instance.
+const STORE_KEY = Symbol.for('@tinacms/astro/forms-store');
+
+type Slot = { [STORE_KEY]?: AsyncLocalStorage<CollectedForm[]> };
+const slot = globalThis as unknown as Slot;
+
+export const formsStore: AsyncLocalStorage<CollectedForm[]> = (slot[
+  STORE_KEY
+] ??= new AsyncLocalStorage<CollectedForm[]>());
+
+export function recordForm(form: CollectedForm): void {
+  const list = formsStore.getStore();
+  if (!list) return;
+  // Same id can appear twice (layout + page both fetch the global). Dedup
+  // and upgrade to `primary` if a later call asserts it.
+  const existing = list.find((entry) => entry.id === form.id);
+  if (existing) {
+    if (form.priority === 'primary') existing.priority = 'primary';
+    return;
+  }
+  list.push(form);
+}
+
+export function sortByPriority(forms: CollectedForm[]): CollectedForm[] {
+  return [...forms].sort(
+    (a, b) =>
+      (a.priority === 'primary' ? 0 : 1) - (b.priority === 'primary' ? 0 : 1)
+  );
+}
+
+export function renderFormPayloadDiv(
+  form: CollectedForm,
+  primary: boolean
+): string {
+  return `<div data-tina-form="${escapeAttr(JSON.stringify(form))}"${
+    primary ? ' data-tina-primary' : ''
+  } hidden></div>`;
+}

package/src/internal/request-context.ts

@@ -0,0 +1,23 @@
+/**
+ * Request-scoped storage so `tina()` can read the current request without
+ * the caller threading `Astro.request` through every loader. The
+ * middleware injected by the `tina()` integration runs every request
+ * through `requestStore.run(...)`.
+ *
+ * Falls through to `undefined` outside a request scope (static builds,
+ * integration not installed) — `tina()` treats that as "no overlay,
+ * no edit mode," so static contexts still produce correct output.
+ *
+ * Stashed on `globalThis` via `Symbol.for(...)` so all bundle copies of
+ * this module share one ALS instance — esbuild inlines it into every
+ * entry that imports it, and per-entry copies wouldn't share state.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+const STORE_KEY = Symbol.for('@tinacms/astro/request-context');
+
+type Slot = { [STORE_KEY]?: AsyncLocalStorage<Request> };
+const slot = globalThis as unknown as Slot;
+
+export const requestStore: AsyncLocalStorage<Request> = (slot[STORE_KEY] ??=
+  new AsyncLocalStorage<Request>());

package/src/is-edit-mode.ts

@@ -0,0 +1,68 @@
+/**
+ * Server-side check: is this request being rendered inside the TinaCMS
+ * admin iframe?
+ *
+ * Resolves true when any of the following hold:
+ *   1. `?tina-edit=1` — explicit signal added by the admin's router for
+ *      deep-link previews.
+ *   2. `Sec-Fetch-Dest: iframe` AND a same-origin Referer under
+ *      `/admin/` — covers the first request after the admin sets
+ *      `iframe.src` to a preview URL.
+ *   3. `Sec-Fetch-Dest: iframe` AND a `__tina_edit=1` cookie — covers
+ *      in-iframe link clicks, where the Referer is the previous preview
+ *      page rather than `/admin/`. The middleware sets the cookie on
+ *      every edit-mode response so the session sticks for the iframe's
+ *      lifetime.
+ *
+ * Direct browser visits set `Sec-Fetch-Dest: document` for top-level
+ * navigations, so a stale cookie left behind in someone's browser can
+ * never trip edit mode outside an iframe — production HTML is byte-
+ * identical to a Tina-free Astro app for end users.
+ */
+export const EDIT_COOKIE = '__tina_edit';
+
+/**
+ * Set-Cookie header value the middleware writes on every edit-mode
+ * response. Refreshing on each response keeps long editing sessions
+ * sticky and short Max-Age limits the blast radius if a cookie lingers.
+ * The `Sec-Fetch-Dest: iframe` gate in `isEditMode` blocks the cookie
+ * from triggering edit mode on top-level visits.
+ */
+export const EDIT_COOKIE_HEADER = `${EDIT_COOKIE}=1; Path=/; SameSite=Strict; Max-Age=3600`;
+
+export function isEditMode(request: Request): boolean {
+  const url = new URL(request.url);
+  if (url.searchParams.get('tina-edit') === '1') return true;
+
+  const dest = request.headers.get('Sec-Fetch-Dest');
+  if (dest !== 'iframe') return false;
+
+  const referer = request.headers.get('Referer');
+  if (referer) {
+    try {
+      const refererUrl = new URL(referer);
+      if (
+        refererUrl.origin === url.origin &&
+        refererUrl.pathname.startsWith('/admin/')
+      ) {
+        return true;
+      }
+    } catch {
+      // Malformed Referer — fall through to cookie check.
+    }
+  }
+
+  return readCookie(request, EDIT_COOKIE) === '1';
+}
+
+export function readCookie(request: Request, name: string): string | null {
+  const header = request.headers.get('Cookie');
+  if (!header) return null;
+  for (const pair of header.split(';')) {
+    const eq = pair.indexOf('=');
+    if (eq === -1) continue;
+    const key = pair.slice(0, eq).trim();
+    if (key === name) return pair.slice(eq + 1).trim();
+  }
+  return null;
+}

package/src/island-route.ts

@@ -0,0 +1,109 @@
+/**
+ * @experimental Built on Astro's `experimental_AstroContainer`. Both APIs
+ * may break in any Astro minor/patch.
+ */
+import { PREVIEW_CONTENT_TYPE, PRIME_HEADER } from '@tinacms/bridge/preview';
+import type { APIRoute } from 'astro';
+import { experimental_AstroContainer as AstroContainer } from 'astro/container';
+import type { AstroComponentFactory } from 'astro/runtime/server/index.js';
+import { escapeAttr } from './internal/escape';
+import {
+  type CollectedForm,
+  formsStore,
+  renderFormPayloadDiv,
+  sortByPriority,
+} from './internal/forms-store';
+import { requestStore } from './internal/request-context';
+
+export interface IslandWrapper {
+  tag: string;
+  className?: string;
+}
+
+export interface IslandConfig {
+  /** Resolve the data the component needs. May ignore the search params. */
+  fetch: (request: Request, params: URLSearchParams) => Promise<unknown>;
+  /** Astro component to render with the fetched data. */
+  component: AstroComponentFactory;
+  /** Outer element the bridge swaps into — must match the page-side wrapper. */
+  wrapper: IslandWrapper;
+  /** Map fetched data + URL params to the component's props. */
+  propsFromData: (
+    data: unknown,
+    params: URLSearchParams
+  ) => Record<string, unknown>;
+}
+
+export type IslandRegistry = Record<string, IslandConfig>;
+
+export function experimental_createIslandRoute(
+  islands: IslandRegistry
+): APIRoute {
+  return async ({ params, request, url }) => {
+    const rejection = rejectIfUnsafe(request);
+    if (rejection) return rejection;
+
+    const island = islands[params.name ?? ''];
+    if (!island) {
+      return new Response(`Unknown island "${params.name}"`, { status: 404 });
+    }
+
+    const priming = request.headers.get(PRIME_HEADER) !== null;
+
+    try {
+      const forms: CollectedForm[] = [];
+      const html = await requestStore.run(request, () =>
+        formsStore.run(forms, async () => {
+          const data = await island.fetch(request, url.searchParams);
+          const container = await AstroContainer.create();
+          return container.renderToString(island.component, {
+            props: island.propsFromData(data, url.searchParams),
+          });
+        })
+      );
+      const body =
+        (priming ? renderFormPayloads(forms) : '') +
+        wrapIsland(html, island.wrapper, url);
+      return new Response(body, {
+        headers: {
+          'Content-Type': 'text/html; charset=utf-8',
+          'Cache-Control': 'no-store',
+        },
+      });
+    } catch {
+      return new Response('Island render failed', { status: 500 });
+    }
+  };
+}
+
+// Bridge issues a same-origin POST with the Tina-preview content-type;
+// production traffic can't match all three signals.
+function rejectIfUnsafe(request: Request): Response | null {
+  if (request.method !== 'POST') {
+    return new Response('Method Not Allowed', { status: 405 });
+  }
+  const contentType = request.headers.get('content-type') ?? '';
+  if (!contentType.includes(PREVIEW_CONTENT_TYPE)) {
+    return new Response('Not Found', { status: 404 });
+  }
+  if (request.headers.get('sec-fetch-site') === 'cross-site') {
+    return new Response('Forbidden', { status: 403 });
+  }
+  return null;
+}
+
+// Keyed on the explicit `primary` flag (not position): each island route
+// call is independent, so position would tag every island's first form.
+function renderFormPayloads(forms: CollectedForm[]): string {
+  return sortByPriority(forms)
+    .map((form) => renderFormPayloadDiv(form, form.priority === 'primary'))
+    .join('');
+}
+
+function wrapIsland(html: string, wrapper: IslandWrapper, url: URL): string {
+  const cls = wrapper.className
+    ? ` class="${escapeAttr(wrapper.className)}"`
+    : '';
+  const marker = escapeAttr(`${url.pathname}${url.search}`);
+  return `<${wrapper.tag}${cls} data-tina-island="${marker}">${html}</${wrapper.tag}>`;
+}

package/src/middleware.ts

@@ -0,0 +1,89 @@
+import type { MiddlewareHandler } from 'astro';
+import { adminOrigins } from './internal/admin-origin';
+import {
+  type CollectedForm,
+  formsStore,
+  renderFormPayloadDiv,
+  sortByPriority,
+} from './internal/forms-store';
+import { requestStore } from './internal/request-context';
+import { EDIT_COOKIE_HEADER, isEditMode } from './is-edit-mode';
+
+const HEAD_CLOSE = '</head>';
+
+export const onRequest: MiddlewareHandler = (context, next) => {
+  // Prerendered routes can never be in edit mode; reading their synthetic
+  // build-time headers would only emit Astro's request.headers warning.
+  if (context.isPrerendered) {
+    (context.locals as { tinaEdit?: boolean }).tinaEdit = false;
+    return next();
+  }
+
+  const editing = isEditMode(context.request);
+  (context.locals as { tinaEdit?: boolean }).tinaEdit = editing;
+
+  const forms: CollectedForm[] = [];
+  return requestStore.run(context.request, () =>
+    formsStore.run(forms, async () => {
+      const response = await next();
+      return editing ? injectEditMode(response, forms) : response;
+    })
+  );
+};
+
+export default onRequest;
+
+async function injectEditMode(
+  response: Response,
+  forms: CollectedForm[]
+): Promise<Response> {
+  const init = editModeInit(response);
+  const contentType = response.headers.get('content-type') ?? '';
+
+  // Redirects / JSON / assets — pass body through and just keep the cookie fresh.
+  if (!contentType.includes('text/html')) {
+    return new Response(response.body, init);
+  }
+
+  const html = await response.text();
+  const headEnd = html.indexOf(HEAD_CLOSE);
+  if (headEnd === -1) {
+    // No </head> to anchor against — return the body untouched.
+    return new Response(html, init);
+  }
+
+  const injection = renderInjection(forms);
+  return new Response(
+    html.slice(0, headEnd) + injection + html.slice(headEnd),
+    init
+  );
+}
+
+function editModeInit(response: Response): ResponseInit {
+  const headers = new Headers(response.headers);
+  // Body length changed; let the runtime re-compute it.
+  headers.delete('content-length');
+  headers.append('Set-Cookie', EDIT_COOKIE_HEADER);
+  return { status: response.status, statusText: response.statusText, headers };
+}
+
+function renderInjection(forms: CollectedForm[]): string {
+  // No explicit priority => sort is a no-op and the first form (page
+  // frontmatter runs before its layout's) wins as primary.
+  const formDivs = sortByPriority(forms)
+    .map((form, i) => renderFormPayloadDiv(form, i === 0))
+    .join('');
+  return formDivs + bridgeScript();
+}
+
+function bridgeScript(): string {
+  const origins = adminOrigins();
+  const initArg = origins ? `{adminOrigin:${JSON.stringify(origins)}}` : '';
+  return (
+    `<script type="module">` +
+    `import{init,refreshForms}from"/admin/bridge.js";` +
+    `init(${initArg});` +
+    `document.addEventListener("astro:page-load",refreshForms);` +
+    `</script>`
+  );
+}