blume 1.7.3 → 2.0.0

package/src/analytics/segment.ts

@@ -0,0 +1,85 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+import { inlineJson, spaPageviews } from "./inline.ts";
+
+/** Segment's CDN, where `segment()` loads analytics.js from when `cdn` is unset. */
+export const SEGMENT_DEFAULT_CDN = "https://cdn.segment.com";
+
+/** The options {@link segment} maps itself. */
+export interface SegmentNamedOptions {
+  /**
+   * Origin of a custom domain that proxies Segment's CDN, e.g.
+   * `https://cdn.example.com`. Defaults to Segment's own.
+   */
+  cdn?: string;
+  /** Write key of the JavaScript source. */
+  key: string;
+}
+
+/**
+ * Options for {@link segment}: the named options plus any other
+ * `analytics.load` option, forwarded verbatim (`integrations`, …). JSON
+ * values only.
+ */
+export type SegmentOptions = SegmentNamedOptions & {
+  [option: string]: JsonValue;
+};
+
+export const segmentOptionsSchema = z
+  .object({
+    cdn: z.string().min(1).optional(),
+    key: z.string().min(1),
+  })
+  .catchall(z.json());
+
+export type SegmentAdapter = AdapterDescriptor<"segment", SegmentOptions>;
+
+export const segmentAdapterSchema = adapterDescriptorSchema(
+  "segment",
+  segmentOptionsSchema
+);
+
+/**
+ * Segment (Twilio Segment) analytics.js. The write key is meant for the
+ * browser — it identifies the source the SDK reports to.
+ */
+export const segment = (options: SegmentOptions): SegmentAdapter => ({
+  kind: "segment",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});
+
+// The SDK sends one `page()` per real page load (the snippet's own call), so
+// client-router swaps are sent here.
+const SEGMENT_SPA_PAGEVIEWS = spaPageviews(
+  "__blumeSegmentPath",
+  "analytics.page();"
+);
+
+/**
+ * The install snippet, with `key` mapped to the write key, `cdn` mapped to
+ * the script origin (and `analytics._cdn`, so the library fetches its
+ * integrations from the same place), and everything else forwarded as the
+ * load options; the object is left off when there is nothing to pass, as the
+ * snippet prints it.
+ */
+export const segmentHead = (options: SegmentOptions): HeadScript[] => {
+  const { cdn, key, ...load } = options;
+  const origin = (cdn ?? SEGMENT_DEFAULT_CDN).replace(/\/+$/u, "");
+  const loadCall =
+    Object.keys(load).length === 0
+      ? `analytics.load(${inlineJson(key)});`
+      : `analytics.load(${inlineJson(key)},${inlineJson(load)});`;
+  const cdnAssign =
+    cdn === undefined ? "" : `analytics._cdn=${inlineJson(origin)};`;
+  return [
+    {
+      attributes: {},
+      content: `!function(){var analytics=window.analytics=window.analytics||[];if(!analytics.initialize)if(analytics.invoked)window.console&&console.error&&console.error("Segment snippet included twice.");else{analytics.invoked=!0;analytics.methods=["trackSubmit","trackClick","trackLink","trackForm","pageview","identify","reset","group","track","ready","alias","debug","page","once","off","on","addSourceMiddleware","addIntegrationMiddleware","setAnonymousId","addDestinationMiddleware"];analytics.factory=function(e){return function(){var t=Array.prototype.slice.call(arguments);t.unshift(e);analytics.push(t);return analytics}};for(var e=0;e<analytics.methods.length;e++){var key=analytics.methods[e];analytics[key]=analytics.factory(key)}analytics.load=function(key,e){var t=document.createElement("script");t.type="text/javascript";t.async=!0;t.src=${inlineJson(`${origin}/analytics.js/v1/`)}+encodeURIComponent(key)+"/analytics.min.js";var n=document.getElementsByTagName("script")[0];n.parentNode.insertBefore(t,n);analytics._loadOptions=e};analytics._writeKey=${inlineJson(key)};${cdnAssign}analytics.SNIPPET_VERSION="4.15.3";${loadCall}analytics.page();}}();${SEGMENT_SPA_PAGEVIEWS}`,
+    },
+  ];
+};

package/src/analytics/vercel.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+
+/** The props of `@vercel/analytics/astro` that {@link vercel} documents. */
+export interface VercelNamedOptions {
+  /** Log every event to the console. Defaults to the component's own rule (on outside production). */
+  debug?: boolean;
+  /** Force the script's environment instead of letting it detect one. */
+  mode?: "auto" | "development" | "production";
+}
+
+/**
+ * Options for {@link vercel}: the documented props plus any other prop of the
+ * official component, forwarded verbatim (`endpoint`, `scriptSrc`, `dsn`, …).
+ * JSON values only; `beforeSend` is a function and can't travel through
+ * config — assign `window.webAnalyticsBeforeSend` from a `script()` adapter
+ * listed before `vercel()` instead.
+ */
+export type VercelOptions = VercelNamedOptions & {
+  [option: string]: JsonValue;
+};
+
+export const vercelOptionsSchema = z
+  .object({
+    debug: z.boolean().optional(),
+    mode: z.enum(["auto", "development", "production"]).optional(),
+  })
+  .catchall(z.json());
+
+export type VercelAdapter = AdapterDescriptor<"vercel", VercelOptions>;
+
+export const vercelAdapterSchema = adapterDescriptorSchema(
+  "vercel",
+  vercelOptionsSchema
+);
+
+/**
+ * Vercel Web Analytics, rendered through the official Astro component, which
+ * injects the first-party script Vercel serves at `/_vercel/insights` once Web
+ * Analytics is enabled for the project. Needs no keys. `@vercel/analytics` is
+ * one of Blume's own dependencies, so the adapter declares no runtime dep.
+ */
+export const vercel = (options: VercelOptions = {}): VercelAdapter => ({
+  kind: "vercel",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});

package/src/astro/adapter-root.ts

@@ -35,21 +35,19 @@ import type { AstroIntegration } from "astro";
  * `config`; an adapter reads `root` from one or both and closes over it for its
  * later build hooks, so overriding it there covers the whole adapter.
  */
-const stripTrailingSlashes = (value: string): string => {
-  let end = value.length;
-
-  while (end > 0 && value[end - 1] === "/") {
-    end -= 1;
-  }
-
-  return value.slice(0, end);
+const directoryUrl = (value: string): URL => {
+  const url = pathToFileURL(value);
+  // URL paths always use `/`, even when the input came from a Windows path.
+  // Keep the root itself intact while collapsing any extra directory slash.
+  url.pathname = `${url.pathname.replace(/\/+$/u, "")}/`;
+  return url;
 };
 
 export const withAdapterRoot = (
   integration: AstroIntegration,
   root: string
 ): AstroIntegration => {
-  const rootUrl = pathToFileURL(`${stripTrailingSlashes(root)}/`);
+  const rootUrl = directoryUrl(root);
   const setup = integration.hooks["astro:config:setup"];
   const done = integration.hooks["astro:config:done"];
 

package/src/astro/component-slots.ts

@@ -1,19 +1,22 @@
+import { isAbsolute, join, relative } from "pathe";
+
 import type {
   ComponentOverrideAnalysis,
   NormalizedOverride,
   OverrideFramework,
 } from "../core/component-overrides.ts";
+import type { IslandSpec } from "./islands.ts";
 
 /**
- * Turn analyzed `components.ts` overrides into the generated `components.ts`
+ * Turn the project's MDX/layout overrides into the generated `components.ts`
  * module plus per-override hydration wrappers.
  *
- * The runtime overrides object already holds bare imported identifiers, so those
- * (when not hydrated) ride through a plain spread. Everything else needs a static
- * import Vite can see: path-string overrides import the file directly, while
- * hydrated overrides get a wrapper `.astro` that applies the `client:*` directive
- * (Astro directives must be written statically). The `islands` group is folded
- * into the MDX component map — it is just `mdx` with a default `client: "visible"`.
+ * Every override is imported statically so Vite can see it: a static override
+ * imports its file directly, while a hydrated one gets a wrapper `.astro` that
+ * applies the `client:*` directive (Astro directives must be written
+ * statically). The `islands/` folder convention feeds the same plan — each
+ * discovered island is an `mdx` entry with its client mode — so a
+ * `components.ts` `mdx` entry of the same name replaces the convention island.
  */
 
 export interface ComponentSlotWrapper {
@@ -22,6 +25,17 @@ export interface ComponentSlotWrapper {
   name: string;
 }
 
+export interface ComponentSlotOptions {
+  /**
+   * The directory the generated `components.ts` is written to. Set by
+   * `blume eject`, whose output has to build from any checkout: every
+   * absolute source path is then imported relative to the file importing it.
+   * The hidden runtime leaves it unset and keeps absolute paths, since it is
+   * regenerated on every run.
+   */
+  relativeTo?: string;
+}
+
 export interface ComponentSlotPlan {
   /** Frameworks used by resolved overrides; enable the matching Astro renderer. */
   frameworks: Set<OverrideFramework>;
@@ -30,12 +44,6 @@ export interface ComponentSlotPlan {
   wrappers: ComponentSlotWrapper[];
 }
 
-const EMPTY_MODULE = `// Generated by Blume. Do not edit.
-import type { ComponentOverride } from "blume/core/define-components.ts";
-export const mdxComponents: Record<string, ComponentOverride> = {};
-export const layoutOverrides: Record<string, ComponentOverride> = {};
-`;
-
 // A user-supplied attribute value interpolated into a generated .astro tag: a
 // stray quote or newline would produce a malformed component and an opaque
 // Astro parse error pointing at the generated file, not the user's config.
@@ -46,7 +54,7 @@ const CLIENT_LOAD = "client:load";
 
 /** Astro client directive for a hydrated override. */
 const directiveFor = (override: NormalizedOverride): string => {
-  const framework = override.source?.framework;
+  const { framework } = override.source;
   switch (override.client) {
     case "idle": {
       return "client:idle";
@@ -70,29 +78,60 @@ const directiveFor = (override: NormalizedOverride): string => {
   }
 };
 
+/**
+ * The specifier a generated file in `fromDir` imports `path` by: relative to
+ * that file when `fromDir` is set and the path is absolute, so the module
+ * resolves wherever the project is checked out; unchanged otherwise (a bare
+ * package specifier, or the hidden runtime's absolute paths).
+ */
+export const importSpecifier = (path: string, fromDir?: string): string => {
+  if (fromDir === undefined || !isAbsolute(path)) {
+    return path;
+  }
+  const specifier = relative(fromDir, path);
+  // A path on another Windows drive has no relative form; keep it absolute.
+  if (isAbsolute(specifier) || specifier.startsWith("../")) {
+    return specifier;
+  }
+  return `./${specifier}`;
+};
+
 const importClause = (variable: string, name: string, path: string): string =>
   name === "default"
     ? `import ${variable} from ${JSON.stringify(path)};`
     : `import { ${name} as ${variable} } from ${JSON.stringify(path)};`;
 
-/** A wrapper `.astro` that statically imports a component and hydrates it. */
-const wrapperContent = (override: NormalizedOverride): string => {
-  // SAFETY: the only caller guards `if (!source)` and bails before invoking
-  // this, so the override always carries a resolved source here.
-  const { name, path } = override.source as NonNullable<
-    NormalizedOverride["source"]
-  >;
-  const clause =
-    name === "default"
-      ? `import Component from ${JSON.stringify(path)};`
-      : `import { ${name} as Component } from ${JSON.stringify(path)};`;
-  return `---
+/**
+ * Frontmatter `Props` alias mirroring the wrapped component's own props, so
+ * `{...Astro.props}` satisfies required props under `astro check` (the spread
+ * of an untyped `Astro.props` contributes nothing to the JSX props type).
+ * `infer P extends object` rather than `Record<string, unknown>` because
+ * interfaces have no implicit index signature and would miss the narrower
+ * constraint. Non-function component types (Vue/Svelte ambient modules) fall
+ * back to an open record, keeping the untyped permissiveness they had.
+ */
+export const wrapperPropsType = (name: string): string =>
+  `type Props = typeof ${name} extends (
+  props: infer P extends object,
+  ...rest: never[]
+) => unknown
+  ? P
+  : Record<string, unknown>;`;
+
+/**
+ * A wrapper `.astro` that statically imports a component and hydrates it.
+ * `fromDir` is the wrapper's own directory when imports must be relative.
+ */
+const wrapperContent = (
+  override: NormalizedOverride,
+  fromDir: string | undefined
+): string => `---
 // Generated by Blume. Do not edit.
-${clause}
+${importClause("Component", override.source.name, importSpecifier(override.source.path, fromDir))}
+${wrapperPropsType("Component")}
 ---
 <Component ${directiveFor(override)} {...Astro.props}><slot /></Component>
 `;
-};
 
 /**
  * A filesystem-safe, injective token for an override key. Distinct keys must
@@ -107,82 +146,83 @@ const sanitize = (value: string): string =>
     (char) => `_${(char.codePointAt(0) ?? 0).toString(16)}_`
   );
 
+/** A convention island as the `mdx` override it is equivalent to. */
+const islandOverride = (island: IslandSpec): NormalizedOverride => ({
+  client: island.client,
+  key: island.name,
+  source: { framework: island.framework, name: "default", path: island.file },
+});
+
+/** An object-literal source for a group's `key: variable` entries. */
+const record = (entries: string[]): string =>
+  entries.length ? `{ ${entries.join(", ")} }` : "{}";
+
+/**
+ * Plan the generated components module for the `islands/` convention plus the
+ * analyzed `components.ts` (empty when the project has none). Within a group
+ * the last entry for a key wins, so `components.ts` overrides a convention
+ * island.
+ */
 export const planComponentSlots = (
-  componentsFile: string | null,
-  analysis: ComponentOverrideAnalysis | null
+  islands: IslandSpec[],
+  analysis: ComponentOverrideAnalysis,
+  options: ComponentSlotOptions = {}
 ): ComponentSlotPlan => {
+  const { relativeTo } = options;
+  const wrapperDir =
+    relativeTo === undefined ? undefined : join(relativeTo, "component-slots");
   const frameworks = new Set<OverrideFramework>();
-  if (!componentsFile) {
-    return { frameworks, module: EMPTY_MODULE, wrappers: [] };
-  }
-  if (!analysis) {
-    return {
-      frameworks,
-      module: `// Generated by Blume. Do not edit.
-import overrides from ${JSON.stringify(componentsFile)};
-export const mdxComponents = overrides.mdx ?? {};
-export const layoutOverrides = overrides.layout ?? {};
-`,
-      wrappers: [],
-    };
-  }
-
   const wrappers: ComponentSlotWrapper[] = [];
   const importLines: string[] = [];
-  // Explicit `key: Variable` map entries, per surface.
-  const mdxEntries: string[] = [];
-  const layoutEntries: string[] = [];
   let counter = 0;
 
-  // Islands are MDX components hydrated by default, so plan them alongside `mdx`.
-  const mdxOverrides = [...analysis.mdx, ...analysis.islands];
-
   const plan = (
-    override: NormalizedOverride,
-    group: "mdx" | "layout",
-    entries: string[]
-  ): void => {
-    const { source } = override;
-    if (source?.framework) {
-      frameworks.add(source.framework);
-    }
-    // Bare identifier, not hydrated: the runtime object already has it.
-    if (override.identifier && !override.client) {
-      return;
-    }
-    if (!source) {
-      // Unresolved (already warned): leave it on the runtime object.
-      return;
+    overrides: NormalizedOverride[],
+    group: "mdx" | "layout"
+  ): string[] => {
+    const byKey = new Map<string, NormalizedOverride>();
+    for (const override of overrides) {
+      byKey.set(override.key, override);
     }
-    const variable = `__blumeSlot${counter}`;
-    counter += 1;
-    if (override.client) {
-      const name = `${group}-${sanitize(override.key)}`;
-      wrappers.push({ content: wrapperContent(override), name });
-      importLines.push(
-        importClause(variable, "default", `./component-slots/${name}.astro`)
-      );
-    } else {
-      importLines.push(importClause(variable, source.name, source.path));
+    const entries: string[] = [];
+    for (const override of byKey.values()) {
+      const { source } = override;
+      if (source.framework) {
+        frameworks.add(source.framework);
+      }
+      const variable = `__blumeSlot${counter}`;
+      counter += 1;
+      if (override.client) {
+        const name = `${group}-${sanitize(override.key)}`;
+        wrappers.push({ content: wrapperContent(override, wrapperDir), name });
+        importLines.push(
+          importClause(variable, "default", `./component-slots/${name}.astro`)
+        );
+      } else {
+        importLines.push(
+          importClause(
+            variable,
+            source.name,
+            importSpecifier(source.path, relativeTo)
+          )
+        );
+      }
+      entries.push(`${JSON.stringify(override.key)}: ${variable}`);
     }
-    entries.push(`${JSON.stringify(override.key)}: ${variable}`);
+    return entries;
   };
 
-  for (const override of mdxOverrides) {
-    plan(override, "mdx", mdxEntries);
-  }
-  for (const override of analysis.layout) {
-    plan(override, "layout", layoutEntries);
-  }
+  const mdxEntries = plan(
+    [...islands.map(islandOverride), ...analysis.mdx],
+    "mdx"
+  );
+  const layoutEntries = plan(analysis.layout, "layout");
 
-  // `overrides.islands` is not spread: every valid island is hydrated, so it is
-  // emitted as an explicit wrapper entry above (raw spreads only carry bare,
-  // non-hydrated identifiers from `mdx`/`layout`).
-  const moduleSource = `// Generated by Blume. Do not edit.
-import overrides from ${JSON.stringify(componentsFile)};
-${importLines.join("\n")}${importLines.length ? "\n" : ""}export const mdxComponents = { ...(overrides.mdx ?? {})${mdxEntries.length ? `, ${mdxEntries.join(", ")}` : ""} };
-export const layoutOverrides = { ...(overrides.layout ?? {})${layoutEntries.length ? `, ${layoutEntries.join(", ")}` : ""} };
+  const module = `// Generated by Blume. Do not edit.
+import type { ComponentOverride } from "blume/core/define-components.ts";
+${importLines.join("\n")}${importLines.length ? "\n" : ""}export const mdxComponents: Record<string, ComponentOverride> = ${record(mdxEntries)};
+export const layoutOverrides: Record<string, ComponentOverride> = ${record(layoutEntries)};
 `;
 
-  return { frameworks, module: moduleSource, wrappers };
+  return { frameworks, module, wrappers };
 };