@withstudiocms/component-registry 0.1.0-beta.1

package/dist/registry/handler.js

@@ -0,0 +1,161 @@
+import { deepmerge, Effect, runEffect } from "@withstudiocms/effect";
+import { z } from "astro/zod";
+import { addVirtualImports, createResolver, defineUtility } from "astro-integration-kit";
+import { convertHyphensToUnderscores, integrationLogger } from "../utils.js";
+import {
+  buildAliasExports,
+  buildVirtualImport,
+  InternalId,
+  NameInternalId,
+  RuntimeInternalId
+} from "./consts.js";
+import { ComponentRegistry } from "./Registry.js";
+const ComponentRegistryHandlerOptionSchema = z.object({
+  config: z.object({
+    /**
+     * The name of the integration
+     */
+    name: z.string(),
+    /**
+     * The virtual module ID for generated imports
+     *
+     * @example 'virtual:my-integration'
+     */
+    virtualId: z.string().optional(),
+    /**
+     * Enables verbose logging
+     */
+    verbose: z.boolean().default(false).optional()
+  }),
+  /**
+   * A record of user-provided component names to file paths.
+   */
+  componentRegistry: z.record(z.string(), z.string()).optional(),
+  /**
+   * A record of built-in component names to file paths.
+   */
+  builtInComponents: z.record(z.string(), z.string()).optional()
+});
+const resolver = Effect.fn(function* (base) {
+  const { resolve: _resolve } = createResolver(base);
+  return Effect.fn(
+    (fn) => Effect.try({
+      try: () => fn(_resolve),
+      catch: (error) => {
+        console.error("Error occurred while resolving component:", error);
+        return new Error("Failed to resolve component", { cause: error });
+      }
+    })
+  );
+});
+const componentRegistryHandler = defineUtility("astro:config:setup")(
+  async (params, {
+    config: { verbose = false, name, virtualId },
+    builtInComponents = {},
+    componentRegistry = {}
+  }) => await runEffect(
+    Effect.gen(function* () {
+      const logger = params.logger.fork(`${name}:component-registry`);
+      const logInfo = { logger, logLevel: "info", verbose };
+      integrationLogger(logInfo, "Setting up component registry...");
+      const [resolve, astroConfigResolve, registry] = yield* Effect.all([
+        resolver(import.meta.url),
+        resolver(params.config.root.pathname),
+        ComponentRegistry
+      ]);
+      const componentKeys = [];
+      const components = [];
+      const componentRegistryToCheck = yield* deepmerge(
+        (fn) => fn({}, builtInComponents, componentRegistry)
+      );
+      const componentRegistryEntries = Object.entries(componentRegistryToCheck);
+      if (Object.keys(componentRegistryToCheck).length === 0) {
+        integrationLogger(logInfo, "No components found in the registry, skipping...");
+      } else {
+        integrationLogger(
+          logInfo,
+          `Checking ${Object.keys(componentRegistryToCheck).length} components...`
+        );
+        integrationLogger(logInfo, "Iterating over component registry entries...");
+        for (const [key, value] of componentRegistryEntries) {
+          integrationLogger(logInfo, `Component "${key}" resolved to "${value}"`);
+          if (!value) {
+            integrationLogger(logInfo, `Component "${key}" is not defined, skipping...`);
+            continue;
+          }
+          if (typeof value !== "string") {
+            integrationLogger(logInfo, `Component "${key}" is not a string, skipping...`);
+            continue;
+          }
+          if (!value.endsWith(".astro")) {
+            integrationLogger(
+              logInfo,
+              `Component "${key}" does not end with .astro, skipping...`
+            );
+            continue;
+          }
+          integrationLogger(logInfo, `Resolving path for component "${key}"...`);
+          const resolvedPath = yield* astroConfigResolve((fn) => fn(value)).pipe(
+            Effect.catchAll((error) => {
+              integrationLogger(
+                logInfo,
+                `Failed to resolve path for component "${key}": ${error}`
+              );
+              return Effect.succeed(null);
+            })
+          );
+          if (!resolvedPath) {
+            integrationLogger(logInfo, `Component "${key}" resolved path is empty, skipping...`);
+            continue;
+          }
+          integrationLogger(logInfo, `Component "${key}" resolved path: "${resolvedPath}"`);
+          const keyName = key.toLowerCase();
+          const safeKeyName = convertHyphensToUnderscores(keyName);
+          componentKeys.push(safeKeyName);
+          components.push(`export { default as ${safeKeyName} } from '${resolvedPath}';`);
+          yield* registry.registerComponentFromFile(resolvedPath, keyName);
+        }
+      }
+      integrationLogger(logInfo, `Total components found: ${componentKeys.length}`);
+      integrationLogger(logInfo, "Extracting component props...");
+      const componentProps = yield* registry.getAllComponents().pipe(
+        Effect.map((map) => Array.from(map.entries())),
+        Effect.map(
+          (array) => array.map(([iName, data]) => ({
+            ...data,
+            name: iName,
+            safeName: convertHyphensToUnderscores(iName)
+          }))
+        )
+      );
+      integrationLogger(logInfo, `Total component props extracted: ${componentProps.length}`);
+      if (verbose && componentProps.length <= 10) {
+        integrationLogger(
+          logInfo,
+          `Registered components:
+${JSON.stringify(componentProps, null, 2)}`
+        );
+      } else {
+        integrationLogger(
+          logInfo,
+          `Registered ${componentProps.length} components. Use verbose mode with fewer components to see details.`
+        );
+      }
+      const virtualRuntimeImport = yield* resolve((fn) => fn("../runtime.js"));
+      addVirtualImports(params, {
+        name,
+        imports: {
+          [InternalId]: buildVirtualImport(componentKeys, componentProps, components),
+          [NameInternalId]: `export default '${name}'; export const name = '${name}';`,
+          [RuntimeInternalId]: `export * from '${virtualRuntimeImport}';`,
+          ...virtualId ? buildAliasExports(virtualId) : {}
+        }
+      });
+      integrationLogger(logInfo, "Component registry setup complete.");
+    }).pipe(Effect.provide(ComponentRegistry.Default))
+  )
+);
+export {
+  ComponentRegistryHandlerOptionSchema,
+  componentRegistryHandler
+};

package/dist/registry/index.d.ts

@@ -0,0 +1,3 @@
+export * from './handler.js';
+export * from './PropsParser.js';
+export * from './Registry.js';

package/dist/registry/index.js

@@ -0,0 +1,3 @@
+export * from "./handler.js";
+export * from "./PropsParser.js";
+export * from "./Registry.js";

package/dist/runtime.d.ts

@@ -0,0 +1,34 @@
+import { componentProps } from 'virtual:component-registry-internal-proxy';
+import type { SSRResult } from 'astro';
+import type { SanitizeOptions } from 'ultrahtml/transformers/sanitize';
+import type { ComponentRegistryEntry } from './types.js';
+export * from './utils.js';
+export { componentProps };
+export type { ComponentRegistryEntry } from './types.js';
+/**
+ * Returns the component registry entries.
+ *
+ * @returns {ComponentRegistryEntry[]} An object mapping safe component names to their registry entries.
+ */
+export declare function getRegistryComponents(): ComponentRegistryEntry[];
+/**
+ * @returns A promise that resolves to an object containing the imported components.
+ */
+export declare function getRendererComponents(): Promise<Record<string, any>>;
+/**
+ * Sets up a component proxy for the renderer.
+ *
+ * @param result - The SSRResult object from Astro.
+ * @returns A promise that resolves to a component proxy containing the components.
+ * @throws {ComponentProxyError} If there is an error during setup, it will be prefixed and logged.
+ */
+export declare function setupRendererComponentProxy(result: SSRResult): Promise<import("./types.js").ComponentType>;
+/**
+ * Creates a renderer function that transforms HTML content using the provided components and sanitization options.
+ *
+ * @param result - The SSRResult object from Astro.
+ * @param sanitizeOpts - Optional sanitization options for the HTML content.
+ * @param preRenderer - An optional function to preprocess the HTML content before rendering.
+ * @returns A function that takes HTML content as input and returns the transformed HTML.
+ */
+export declare function createRenderer(result: SSRResult, sanitizeOpts?: SanitizeOptions, preRenderer?: (content: string) => Promise<string>): Promise<(content: string) => Promise<string>>;

package/dist/runtime.js

@@ -0,0 +1,49 @@
+import * as registry from "virtual:component-registry-internal-proxy";
+import { componentKeys, componentProps } from "virtual:component-registry-internal-proxy";
+import { name } from "virtual:component-registry-internal-proxy/name";
+import { createComponentProxy } from "./component-proxy/index.js";
+import { toComponentProxyError } from "./errors.js";
+import { transformHTML } from "./transform-html.js";
+import { convertUnderscoresToHyphens } from "./utils.js";
+export * from "./utils.js";
+function getRegistryComponents() {
+  return componentProps;
+}
+const buildPrefix = (key, name2) => `Failed to import component "${key}" from [${name2}] component-registry`;
+async function getRendererComponents() {
+  const predefinedComponents = {};
+  for (const key of componentKeys) {
+    try {
+      predefinedComponents[convertUnderscoresToHyphens(key)] = registry[key];
+    } catch (e) {
+      if (e instanceof Error) {
+        throw toComponentProxyError(e, buildPrefix(key, name));
+      }
+      throw toComponentProxyError(new Error("Unknown error"), buildPrefix(key, name));
+    }
+  }
+  return predefinedComponents;
+}
+async function setupRendererComponentProxy(result) {
+  const components = await getRendererComponents();
+  return createComponentProxy(result, components);
+}
+async function createRenderer(result, sanitizeOpts, preRenderer) {
+  const components = await setupRendererComponentProxy(result);
+  return async (content) => {
+    let html;
+    if (preRenderer && typeof preRenderer === "function") {
+      html = await preRenderer(content);
+    } else {
+      html = content;
+    }
+    return await transformHTML(html, components, sanitizeOpts);
+  };
+}
+export {
+  componentProps,
+  createRenderer,
+  getRegistryComponents,
+  getRendererComponents,
+  setupRendererComponentProxy
+};

package/dist/transform-html.d.ts

@@ -0,0 +1,11 @@
+import type { SanitizeOptions } from 'ultrahtml/transformers/sanitize';
+import type { ComponentType } from './types.js';
+/**
+ * Transforms the provided HTML string by applying sanitization and component swapping.
+ *
+ * @param html - The HTML string to be transformed.
+ * @param components - A record of components to be swapped within the HTML. The keys are component names and the values are the corresponding component implementations.
+ * @param sanitizeOpts - Optional sanitization options to be applied to the HTML.
+ * @returns A promise that resolves to the transformed HTML string.
+ */
+export declare function transformHTML(html: string, components: ComponentType, sanitizeOpts?: SanitizeOptions): Promise<string>;

package/dist/transform-html.js

@@ -0,0 +1,10 @@
+import { transform } from "ultrahtml";
+import sanitize from "ultrahtml/transformers/sanitize";
+import swap from "ultrahtml/transformers/swap";
+import { dedent } from "./utils.js";
+async function transformHTML(html, components, sanitizeOpts) {
+  return await transform(dedent(html), [sanitize(sanitizeOpts), swap(components)]);
+}
+export {
+  transformHTML
+};

package/dist/types.d.ts

@@ -0,0 +1,64 @@
+export type ComponentType = Record<string, any>;
+export type AstroProps = Record<string, any>;
+export type AstroComponentChildren = {
+    value: any;
+};
+/**
+ * Represents a JSDoc tag with its name and optional text content.
+ *
+ * @property tagName - The name of the JSDoc tag (e.g., 'param', 'returns').
+ * @property text - Optional text associated with the tag, such as a description or type.
+ */
+export interface JSDocTag {
+    tagName: string;
+    text?: string;
+    name?: string;
+    type?: string;
+}
+/**
+ * Represents a property of an Astro component.
+ *
+ * @property name - The name of the property.
+ * @property type - The type of the property as a string.
+ * @property optional - Indicates whether the property is optional.
+ * @property description - An optional description of the property.
+ * @property defaultValue - An optional default value for the property.
+ */
+export interface AstroComponentProp {
+    readonly name: string;
+    readonly type: string;
+    readonly optional: boolean;
+    readonly description?: string;
+    readonly defaultValue?: string;
+    readonly jsDocTags?: JSDocTag[];
+}
+/**
+ * Represents the properties of an Astro component.
+ *
+ * @property name - The unique name of the Astro component.
+ * @property props - A readonly array of properties (`AstroComponentProp`) associated with the component.
+ */
+export interface AstroComponentProps {
+    readonly name: string;
+    readonly props: ReadonlyArray<AstroComponentProp>;
+}
+/**
+ * Represents an entry in the component registry.
+ *
+ * Extends the `AstroComponentProps` interface to include additional metadata.
+ *
+ * @property safeName - A readonly string representing a safe, unique identifier for the component.
+ */
+export interface ComponentRegistryEntry extends AstroComponentProps {
+    readonly safeName: string;
+}
+/**
+ * Represents the result of validating a set of properties.
+ *
+ * @property valid - Indicates whether the validation was successful.
+ * @property errors - A readonly array of error messages describing validation failures.
+ */
+export interface PropValidationResult {
+    readonly valid: boolean;
+    readonly errors: ReadonlyArray<string>;
+}

package/dist/utils.d.ts

@@ -0,0 +1,52 @@
+import type { AstroIntegrationLogger } from 'astro';
+/**
+ * Options for configuring the logger.
+ *
+ * @property logLevel - The minimum level of messages to log. Can be 'info', 'warn', 'error', or 'debug'.
+ * @property logger - The logger instance to use, typically an AstroIntegrationLogger.
+ * @property verbose - Optional flag to enable verbose logging output.
+ */
+export type LoggerOpts = {
+    logLevel: 'info' | 'warn' | 'error' | 'debug';
+    logger: AstroIntegrationLogger;
+    verbose?: boolean;
+};
+/**
+ * Logs a message using the provided logger and options.
+ *
+ * @param opts - The logger options, including log level, logger instance, and verbosity flag.
+ * @param opts.logLevel - The log level to use (e.g., 'debug', 'info', 'warn', 'error').
+ * @param opts.logger - The logger object with methods corresponding to log levels.
+ * @param opts.verbose - If true, always logs the message; if false, logs only if the level is not 'debug' or 'info'.
+ * @param message - The message to log.
+ * @returns A promise that resolves when logging is complete.
+ */
+export declare const integrationLogger: (opts: LoggerOpts, message: string) => Promise<void>;
+/**
+ * Converts all hyphens in a given string to underscores.
+ *
+ * @param str - The input string containing hyphens to be converted.
+ * @returns A new string with all hyphens replaced by underscores.
+ */
+export declare function convertHyphensToUnderscores(str: string): string;
+/**
+ * Converts all underscores in a given string to hyphens.
+ *
+ * @param str - The input string containing underscores to be converted.
+ * @returns A new string with all underscores replaced by hyphens.
+ */
+export declare function convertUnderscoresToHyphens(str: string): string;
+/**
+ * Determines the indentation of a given line of text.
+ *
+ * @param ln - The line of text to analyze.
+ * @returns The leading whitespace characters of the line, or an empty string if there is no indentation.
+ */
+export declare function getIndent(ln: string): string;
+/**
+ * Removes leading indentation from a multi-line string.
+ *
+ * @param str - The string from which to remove leading indentation.
+ * @returns The dedent string output.
+ */
+export declare function dedent(str: string): string;

package/dist/utils.js

@@ -0,0 +1,41 @@
+const integrationLogger = async (opts, message) => {
+  const { logLevel, logger, verbose } = opts;
+  switch (verbose) {
+    case true:
+      logger[logLevel](message);
+      break;
+    case false:
+      if (logLevel !== "debug" && logLevel !== "info") {
+        logger[logLevel](message);
+      }
+      break;
+    default:
+      logger[logLevel](message);
+  }
+};
+function convertHyphensToUnderscores(str) {
+  return str.replace(/-/g, "_");
+}
+function convertUnderscoresToHyphens(str) {
+  return str.replace(/_/g, "-");
+}
+function getIndent(ln) {
+  if (ln.trimStart() === ln) return "";
+  return ln.slice(0, ln.length - ln.trimStart().length);
+}
+function dedent(str) {
+  const lns = str.replace(/^[\r\n]+/, "").split("\n");
+  let indent = getIndent(lns[0]);
+  if (indent.length === 0 && lns.length > 1) {
+    indent = getIndent(lns[1]);
+  }
+  if (indent.length === 0) return lns.join("\n");
+  return lns.map((ln) => ln.startsWith(indent) ? ln.slice(indent.length) : ln).join("\n");
+}
+export {
+  convertHyphensToUnderscores,
+  convertUnderscoresToHyphens,
+  dedent,
+  getIndent,
+  integrationLogger
+};

package/dist/virtual.d.ts

@@ -0,0 +1,80 @@
+declare module 'virtual:component-registry-internal-proxy' {
+	/**
+	 * List of component keys that are registered in the component registry.
+	 */
+	export const componentKeys: string[];
+
+	/**
+	 * List of component properties that are registered in the component registry.
+	 *
+	 * Each entry in the array is an object with a `name` and `props` property.
+	 * The `props` property is an array of objects representing the properties of the component.
+	 */
+	export const componentProps: import('./types.js').ComponentRegistryEntry[];
+}
+
+declare module 'virtual:component-registry-internal-proxy/name' {
+	export const name: string;
+	export default name;
+}
+
+declare module 'virtual:component-registry-internal-proxy/runtime' {
+	/**
+	 * Represents an entry in the component registry.
+	 *
+	 * Extends the `AstroComponentProps` interface to include additional metadata.
+	 *
+	 * @property safeName - A readonly string representing a safe, unique identifier for the component.
+	 */
+	export type ComponentRegistryEntry = import('./runtime.js').ComponentRegistryEntry;
+
+	/**
+	 * Imports components by their keys from the 'studiocms:markdown-remark/user-components' module.
+	 *
+	 * @param keys - An array of strings representing the keys of the components to import.
+	 * @returns A promise that resolves to an object containing the imported components.
+	 * @throws {MarkdownRemarkError} If any component fails to import, an error is thrown with a prefixed message.
+	 * @deprecated This function is deprecated and will be removed in future versions.
+	 * Use `getRendererComponents` instead for importing components from the component registry.
+	 */
+	export const importComponentsKeys: typeof import('./runtime.js').importComponentsKeys;
+
+	/**
+	 * @returns A promise that resolves to an object containing the imported components.
+	 */
+	export const getRendererComponents: typeof import('./runtime.js').getRendererComponents;
+
+	/**
+	 * Returns the component registry entries.
+	 *
+	 * @returns {ComponentRegistryEntry[]} An object mapping safe component names to their registry entries.
+	 */
+	export const getRegistryComponents: typeof import('./runtime.js').getRegistryComponents;
+
+	/**
+	 * List of component properties that are registered in the component registry.
+	 *
+	 * Each entry in the array is an object with a `name` and `props` property.
+	 * The `props` property is an array of objects representing the properties of the component.
+	 */
+	export const componentProps: import('./runtime.js').ComponentRegistryEntry[];
+
+	/**
+	 * Converts all underscores in a given string to hyphens.
+	 *
+	 * @param str - The input string containing underscores to be converted.
+	 * @returns A new string with all underscores replaced by hyphens.
+	 */
+	export const convertUnderscoresToHyphens: typeof import('./runtime.js').convertUnderscoresToHyphens;
+	/**
+	 * Converts all hyphens in a given string to underscores.
+	 *
+	 * @param str - The input string containing hyphens to be converted.
+	 * @returns A new string with all hyphens replaced by underscores.
+	 */
+	export const convertHyphensToUnderscores: typeof import('./runtime.js').convertHyphensToUnderscores;
+
+	export const setupRendererComponentProxy: typeof import('./runtime.js').setupRendererComponentProxy;
+
+	export const createRenderer: typeof import('./runtime.js').createRenderer;
+}

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@withstudiocms/component-registry",
+  "version": "0.1.0-beta.1",
+  "description": "Component Registry Utilities for Astro",
+  "license": "MIT",
+  "author": {
+    "name": "withstudiocms",
+    "url": "https://studiocms.dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/withstudiocms/studiocms.git",
+    "directory": "packages/@withstudiocms/component-registry"
+  },
+  "keywords": [
+    "astro-studiocms",
+    "cms",
+    "studiocms",
+    "astro",
+    "withastro"
+  ],
+  "homepage": "https://studiocms.dev",
+  "contributors": [
+    "Adammatthiesen",
+    "jdtjenkins",
+    "dreyfus92",
+    "code.spirit"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "LICENSE",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./component-proxy": {
+      "types": "./dist/component-proxy/index.d.ts",
+      "default": "./dist/component-proxy/index.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "default": "./dist/errors.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "default": "./dist/runtime.js"
+    },
+    "./transform-html": {
+      "types": "./dist/transform-html.d.ts",
+      "default": "./dist/transform-html.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    },
+    "./utils": {
+      "types": "./dist/utils.d.ts",
+      "default": "./dist/utils.js"
+    }
+  },
+  "type": "module",
+  "dependencies": {
+    "astro-integration-kit": "^0.19.0",
+    "ts-morph": "^26.0.0",
+    "ultrahtml": "1.6.0",
+    "@withstudiocms/effect": "0.1.0-beta.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.2"
+  },
+  "peerDependencies": {
+    "astro": "^5.12.9"
+  },
+  "scripts": {
+    "build": "buildkit build 'src/**/*.{ts,d.ts}'",
+    "dev": "buildkit dev 'src/**/*.{ts,d.ts}'",
+    "test": "buildkit test 'test/**/*.test.js'",
+    "typecheck": "tspc -p tsconfig.tspc.json"
+  }
+}