@blinkk/root 3.0.2 → 3.0.4

package/dist/core/config.d.ts

@@ -0,0 +1,285 @@
+import { UserConfig as ViteUserConfig } from 'vite';
+import { JsxRenderOptions } from '../jsx/jsx-render.js';
+import { HtmlMinifyOptions } from '../render/html-minify.js';
+import { HtmlPrettyOptions } from '../render/html-pretty.js';
+import { Plugin } from './plugin.js';
+import { PodConfig } from './pod.js';
+import { RequestMiddleware } from './types.js';
+export interface RootUserConfig {
+    /**
+     * Canonical domain the website will serve on. Useful for things like the
+     * sitemap, SEO tags, etc.
+     */
+    domain?: string;
+    /**
+     * The base URL path that the site will serve on. Defaults to `/`;
+     */
+    base?: string;
+    /**
+     * Config for auto-injecting custom element dependencies.
+     */
+    elements?: {
+        /**
+         * A list of directories to use to look for custom elements. The dir path
+         * should be relative to the project dir, e.g. "path/to/elements".
+         */
+        include?: string[];
+        /**
+         * A list of RegEx patterns to exclude. The string passed to the RegEx is
+         * the file URL relative to the project root, e.g. "/elements/foo/foo.ts".
+         */
+        exclude?: RegExp[];
+    };
+    /**
+     * Config for manually injecting stylesheet entries as
+     * `<link rel="stylesheet">` tags.
+     */
+    styles?: {
+        /**
+         * Project-root-relative stylesheet files to include on every rendered
+         * page, e.g. `styles/index.css`.
+         *
+         * Entries are normalized as URL paths, so both `styles/index.css` and
+         * `/styles/index.css` resolve to `/styles/index.css`.
+         *
+         * Manual entries are injected first, then auto-collected CSS
+         * dependencies are merged after. Duplicate URLs are de-duped so each
+         * stylesheet is only injected once.
+         */
+        entries?: string[];
+    };
+    /**
+     * Config options for localization and internationalization.
+     */
+    i18n?: RootI18nConfig;
+    /**
+     * Config options for the Root.js express server.
+     */
+    server?: RootServerConfig;
+    /**
+     * Build options for the `root build` command.
+     */
+    build?: RootBuildConfig;
+    /**
+     * Vite config.
+     * @see {@link https://vitejs.dev/config/} for more information.
+     */
+    vite?: ViteUserConfig;
+    /**
+     * Config for the built-in JSX-to-HTML renderer.
+     *
+     * - `mode: 'pretty'` (default) — block-level elements render on their own
+     *   line with no indentation.
+     * - `mode: 'minimal'` — compact output with no extra whitespace.
+     *
+     * Use `blockElements` to specify additional custom element tag names that
+     * should be treated as block-level in pretty mode.
+     *
+     * @example
+     * ```ts
+     * export default defineConfig({
+     *   jsxRenderer: {
+     *     mode: 'pretty',
+     *     blockElements: ['my-card', 'my-section'],
+     *   },
+     * });
+     * ```
+     */
+    jsxRenderer?: JsxRenderOptions;
+    /**
+     * Whether to automatically minify HTML output. This is enabled by default,
+     * in order to disable, pass `minifyHtml: false` to root.config.ts.
+     */
+    minifyHtml?: boolean;
+    /**
+     * Options to pass to html-minifier-terser.
+     */
+    minifyHtmlOptions?: HtmlMinifyOptions;
+    /**
+     * Whether to pretty print HTML output.
+     */
+    prettyHtml?: boolean;
+    /**
+     * Options to pass to js-beautify.
+     */
+    prettyHtmlOptions?: HtmlPrettyOptions;
+    /**
+     * Whether to include a sitemap.xml file to the build output.
+     */
+    sitemap?: boolean;
+    /**
+     * Plugins.
+     */
+    plugins?: Plugin[];
+    /**
+     * Per-pod user-level overrides. The key is the pod name as declared in
+     * Pod.name.
+     */
+    pods?: Record<string, PodConfig>;
+    /**
+     * Experimental config options. Note: these are subject to change at any time.
+     */
+    experiments?: {
+        /** Whether to render `<script>` tags with `async`. */
+        enableScriptAsync?: boolean;
+    };
+}
+export type RootConfig = RootUserConfig & {
+    rootDir: string;
+};
+export interface LocaleGroup {
+    label?: string;
+    locales: string[];
+}
+export interface RootI18nConfig {
+    /**
+     * Locales enabled for the site.
+     */
+    locales?: string[];
+    /**
+     * The default locale to use. Defaults is `en`.
+     */
+    defaultLocale?: string;
+    /**
+     * URL format for localized content. Default is `/[locale]/[base]/[path]`.
+     */
+    urlFormat?: string;
+    /**
+     * Localization groups, to help UIs (like Root.js CMS) logically group
+     * locales.
+     */
+    groups?: Record<string, LocaleGroup>;
+}
+export interface RootBuildConfig {
+    /**
+     * Excludes the `/intl/{defaultLocale}/...` path from the SSG build.
+     */
+    excludeDefaultLocaleFromIntlPaths?: boolean;
+}
+export interface RootRedirectConfig {
+    /**
+     * The source path to redirect. Accepts placeholders in the format
+     * `[key]` or `[...key]`. Use `[key]` for single segments and
+     * `[...key]` for multi-segment wildcards.
+     * @example "/old-path/[id]" or "/old-path/[...wildcard]"
+     */
+    source: string;
+    /**
+     * The destination to redirect to. Placeholders from the source can
+     * optionally be inserted into the destination using the same
+     * placeholder format.
+     * @example "/new-path/[id]" or "/new-path/[...wildcard]"
+     */
+    destination: string;
+    /**
+     * The redirect type (`301` = permanent, `302` = temporary). If unspecified,
+     * defaults to `302` (temporary).
+     */
+    type?: 301 | 302;
+}
+export interface RootHeaderConfig {
+    /** A glob pattern match (regex not supported yet). */
+    source: string;
+    headers: Array<{
+        key: string;
+        value: string;
+    }>;
+}
+export interface ContentSecurityPolicyConfig {
+    directives?: Record<string, string[]>;
+    reportOnly?: boolean;
+}
+export interface XFrameOptionsConfig {
+    action: 'DENY' | 'SAMEORIGIN';
+}
+export interface RootSecurityConfig {
+    /**
+     * Content-Security-Policy config. If enabled, a nonce is auto-generated
+     * for every request and appended to script and stylesheet tags. You can
+     * validate your CSP headers using a tool like {@link https://csp-evaluator.withgoogle.com/}.
+     *
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP}
+     */
+    contentSecurityPolicy?: ContentSecurityPolicyConfig | boolean;
+    /**
+     * Strict-Transport-Security config. When enabled, the header value is set
+     * to `Strict-Transport-Security: max-age=63072000; includeSubDomains; preload`.
+     */
+    strictTransportSecurity?: boolean;
+    /**
+     * X-Content-Type-Options config. When enabled, the header value is set to
+     * `X-Content-Type-Options: nosniff`.
+     */
+    xContentTypeOptions?: boolean;
+    /**
+     * X-Frame-Options config. Setting this value to `true` will default the
+     * header value to `X-Frame-Options: SAMEORIGIN`.
+     *
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options}
+     */
+    xFrameOptions?: 'DENY' | 'SAMEORIGIN' | boolean;
+    /**
+     * X-XSS-Protection config. When enabled, the header value is set to
+     * `X-XSS-Protection: 1; mode=block`.
+     */
+    xXssProtection?: boolean;
+}
+export interface RootServerConfig {
+    /**
+     * An array of middleware to add to the express server. These middleware are
+     * added to the beginning of the express app.
+     */
+    middlewares?: RequestMiddleware[];
+    /**
+     * The `trailingSlash` config allows you to control how the server handles
+     * trailing slashes. This config only affects URLs that do not have a file
+     * extension (i.e. HTML paths).
+     *
+     * - When `true`, the server redirects URLs to add a trailing slash
+     * - When `false`, the server redirects URLs to remove a trailing slash
+     * - When unspecified, the server allows URLs with and without trailing slash
+     */
+    trailingSlash?: boolean;
+    /**
+     * Cookie secret for the session middleware.
+     *
+     * Generate a secure secret with:
+     * ```
+     * node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+     * ```
+     */
+    sessionCookieSecret?: string | string[];
+    /**
+     * List of redirects. Supports optional wildcards.
+     *
+     * @example
+     * ```ts
+     * redirects: [
+     *   {
+     *     source: '/old-path/[id]',
+     *     destination: '/new-path/[id]',
+     *     type: 301,
+     *   },
+     *   {
+     *     source: '/old-path/[...wildcard]',
+     *     destination: '/new-path/[...wildcard]',
+     *   },
+     * ]
+     * ```
+     */
+    redirects?: RootRedirectConfig[];
+    /**
+     * HTTP headers to add to a response.
+     */
+    headers?: RootHeaderConfig[];
+    /**
+     * HTTP security settings. By default, all security settings are enabled with
+     * commonly used default values.
+     */
+    security?: RootSecurityConfig;
+    /**
+     * Home page URL path, which is printed when the dev server starts.
+     */
+    homePagePath?: string;
+}
+export declare function defineConfig(config: RootUserConfig): RootUserConfig;

package/dist/core/core.d.ts

@@ -0,0 +1,14 @@
+export * from './config.js';
+export { Body } from './components/Body.js';
+export { Head } from './components/Head.js';
+export { Html, HTML_CONTEXT } from './components/Html.js';
+export { Script } from './components/Script.js';
+export { StringParamsContext, StringParamsProvider, useStringParams, } from './hooks/useStringParams.js';
+export { TranslationMiddlewareProvider, useTranslationMiddleware, } from './hooks/useTranslationsMiddleware.js';
+export { I18nContext, useI18nContext, getTranslations, } from './hooks/useI18nContext.js';
+export { RequestContext, useRequestContext } from './hooks/useRequestContext.js';
+export { useTranslations } from './hooks/useTranslations.js';
+export * from './pod.js';
+export * from './plugin.js';
+export * from './types.js';
+export * from '../utils/url-path-params.js';

package/dist/core/hooks/useI18nContext.d.ts

@@ -0,0 +1,11 @@
+export declare const I18N_CONTEXT: import("preact").Context<I18nContext | null>;
+export interface I18nContext {
+    locale: string;
+    translations: Record<string, string>;
+}
+/**
+ * A hook that returns information about the current i18n context, including the
+ * locale for the given route and a map of translations for that locale.
+ */
+export declare function useI18nContext(): I18nContext;
+export declare function getTranslations(locale: string): Record<string, string>;

package/dist/core/hooks/useRequestContext.d.ts

@@ -0,0 +1,36 @@
+import { Route } from '../types.js';
+export interface RequestContext {
+    /**
+     * The current request path, e.g. `/foo/bar` (default route path) or
+     * `/{locale}/foo/bar` (localized route path).
+     */
+    currentPath: string;
+    /** The route file. */
+    route: Route;
+    /**
+     * Route param values. E.g. for a route like `routes/blog/[slug].tsx`,
+     * visiting `/blog/foo` will pass {slug: 'foo'} here.
+     */
+    routeParams: Record<string, string>;
+    /** Props passed to the route's server component. */
+    props: any;
+    /** The current locale. */
+    locale: string;
+    /** Translations map for the current locale. */
+    translations: Record<string, string>;
+    /** CSP nonce value. */
+    nonce?: string;
+}
+export declare const REQUEST_CONTEXT: import("preact").Context<RequestContext | null>;
+/**
+ * A hook that returns information about the current route.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const ctx = useRequestContext();
+ * ctx.route.src;
+ * // => 'routes/index.tsx'
+ * ```
+ */
+export declare function useRequestContext(): RequestContext;

package/dist/core/hooks/useStringParams.d.ts

@@ -0,0 +1,34 @@
+import { ComponentChildren, FunctionalComponent } from 'preact';
+export type StringParamsContext = Record<string, string>;
+export declare const STRING_PARAMS_CONTEXT: import("preact").Context<StringParamsContext | null>;
+export interface StringParamsProviderProps {
+    value?: StringParamsContext;
+    children?: ComponentChildren;
+}
+export declare const StringParamsProvider: FunctionalComponent<StringParamsProviderProps>;
+/**
+ * A hook that returns a map of string params, configured via the
+ * `StringParamsProvider` context provider. These params are automatically
+ * applied to the `useTranslations()` hook.
+ *
+ *
+ * Usage:
+ *
+ * ```
+ * export default function Page() {
+ *   return (
+ *     <StringParamsProvider value={{name: 'Alice'}}>
+ *       <SayHello />
+ *     </StringParamsProvider>
+ *   );
+ * }
+ *
+ * function SayHello() {
+ *   const t = useTranslations();
+ *   return <h1>{t('Hello, {name}!')}</h1>;
+ * }
+ * ```
+ *
+ * This should render `<h1>Hello, Alice!</h1>`.
+ */
+export declare function useStringParams(): StringParamsContext;

package/dist/core/hooks/useTranslations.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A hook that returns a function that can be used to translate a string, and
+ * optionally replace any parameterized values that are surrounded in curly
+ * braces.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const t = useTranslations();
+ * t('Hello {name}', {name: 'Bob'});
+ * // => 'Bounjour Bob'
+ * ```
+ */
+export declare function useTranslations(): (str: string, params?: Record<string, string | number>) => string;
+/**
+ * Cleans a string that's used for translations. Performs the following:
+ * - Removes any leading/trailing whitespace
+ * - Removes spaces at the end of any line
+ */
+export declare function normalizeString(str: string): string;

package/dist/core/hooks/useTranslationsMiddleware.d.ts

@@ -0,0 +1,25 @@
+import { ComponentChildren, FunctionalComponent } from 'preact';
+type TransformFn = (str: string) => string;
+export interface TranslationMiddleware {
+    /** Transform the string before translation lookup. */
+    beforeTranslate?: TransformFn;
+    /** Transform the string after translation lookup. */
+    afterTranslate?: TransformFn;
+    /** Transform the string before `{param}` values are replaced. */
+    beforeReplaceParams?: TransformFn;
+    /** Transform the string after `{param}` values are replaced. */
+    afterReplaceParams?: TransformFn;
+}
+export interface TranslationMiddlewareContext {
+    beforeTranslateFns: TransformFn[];
+    afterTranslateFns: TransformFn[];
+    beforeReplaceParamsFns: TransformFn[];
+    afterReplaceParamsFns: TransformFn[];
+}
+export interface TranslationMiddlewareProviderProps {
+    value?: TranslationMiddleware;
+    children?: ComponentChildren;
+}
+export declare const TranslationMiddlewareProvider: FunctionalComponent<TranslationMiddlewareProviderProps>;
+export declare function useTranslationMiddleware(): TranslationMiddlewareContext;
+export {};

package/dist/core/pages/DevErrorPage.d.ts

@@ -0,0 +1,9 @@
+import { Request, Route, RouteParams } from '../types.js';
+interface DevErrorPageProps {
+    req: Request;
+    route?: Route;
+    routeParams?: RouteParams;
+    error: any;
+}
+export declare function DevErrorPage(props: DevErrorPageProps): import("preact").JSX.Element;
+export {};

package/dist/core/pages/DevNotFoundPage.d.ts

@@ -0,0 +1,10 @@
+import { Request, Route } from '../types.js';
+interface DevNotFoundPageProps {
+    req: Request;
+    sitemap: Record<string, {
+        route: Route;
+        params: Record<string, string>;
+    }>;
+}
+export declare function DevNotFoundPage(props: DevNotFoundPageProps): import("preact").JSX.Element;
+export {};

package/dist/core/pages/ErrorPage.d.ts

@@ -0,0 +1,9 @@
+import { ComponentChildren } from 'preact';
+export interface ErrorPageProps {
+    code: number;
+    title?: string;
+    message?: string;
+    children?: ComponentChildren;
+    align?: 'center';
+}
+export declare function ErrorPage(props: ErrorPageProps): import("preact").JSX.Element;

package/dist/core/plugin.d.ts

@@ -0,0 +1,80 @@
+import { PluginOption as VitePlugin } from 'vite';
+import { RootConfig } from './config.js';
+import { Pod, PodFactory } from './pod.js';
+import { NextFunction, Request, Response, Server } from './types.js';
+type MaybePromise<T> = T | Promise<T>;
+type PreBuildHook = (rootConfig: RootConfig) => MaybePromise<void>;
+export interface PostBuildOptions {
+    /** Whether the build was SSR-only (no SSG pre-rendering). */
+    ssrOnly?: boolean;
+}
+type PostBuildHook = (rootConfig: RootConfig, options?: PostBuildOptions) => MaybePromise<void>;
+export type ConfigureServerHook = (server: Server, options: ConfigureServerOptions) => MaybePromise<void> | MaybePromise<() => void>;
+export interface ConfigureServerOptions {
+    type: 'dev' | 'preview' | 'prod';
+    rootConfig: RootConfig;
+}
+export interface PluginHooks {
+    /**
+     * Hook that runs before the build starts.
+     */
+    preBuild?: PreBuildHook;
+    /**
+     * Hook that runs after the build completes.
+     */
+    postBuild?: PostBuildHook;
+    /**
+     * Post-render hook that's called before the HTML is rendered to the response
+     * object. If a string is returned from this hook, it will replace the
+     * rendered HTML.
+     */
+    preRender?: (html: string) => void | MaybePromise<string>;
+}
+export interface Plugin {
+    [key: string]: any;
+    /** The name of the plugin. */
+    name?: string;
+    /**
+     * Configures the root.js express server. Any middleware defined by the plugin
+     * will be added to the server first. If a callback fn is returned, it will
+     * be called after the root.js middlewares are added.
+     */
+    configureServer?: ConfigureServerHook;
+    /**
+     * Hook for file changes.
+     */
+    onFileChange?: (eventName: 'add' | 'addDir' | 'change' | 'unlink' | 'unlinkDir', path: string) => void;
+    /**
+     * Returns a list of deps to bundle for ssr. The files will be bundled and
+     * output to `dist/server/`. The return value should be a map of
+     * `{output filename => input filepath}`.
+     *
+     * E.g. a value of `{foo: 'path/to/bar.js'}` will output `dist/server/foo.js`.
+     *
+     * @experimental This config is subject to change to be incorporated into a
+     * broader config option called "ssr" or "ssrOptions".
+     */
+    ssrInput?: () => {
+        [entryAlias: string]: string;
+    };
+    /** Adds vite plugins. */
+    vitePlugins?: VitePlugin[];
+    /** Plugin lifecycle callback hooks. */
+    hooks?: PluginHooks;
+    /** Custom 404 handler. */
+    handle404?: (req: Request, res: Response, next: NextFunction) => void | Promise<void>;
+    /**
+     * Registers a pod (a mini root.js site) that gets merged into the parent
+     * site at dev/build time. A plugin may return a single pod, an array of
+     * pods, or a factory that receives the rootConfig.
+     */
+    pod?: Pod | Pod[] | PodFactory;
+}
+/**
+ * Runs the pre-hook configureServer method of every plugin, calls a callback
+ * function, and then runs the configureServer's post-hook if provided. Plugins
+ * provide a post-hook by returning a callback function from configureServer.
+ */
+export declare function configureServerPlugins(server: Server, callback: () => Promise<void>, plugins: Plugin[], options: ConfigureServerOptions): Promise<void>;
+export declare function getVitePlugins(plugins: Plugin[]): VitePlugin[];
+export {};

package/dist/core/pod.d.ts

@@ -0,0 +1,54 @@
+import { PluginOption as VitePlugin } from 'vite';
+import { RootConfig } from './config.js';
+export interface Pod {
+    /** Unique pod name, e.g. '@blinkk/root-docs-pod'. */
+    name: string;
+    /**
+     * URL prefix for pod routes. Routes within the pod are served under this
+     * mount path. Defaults to '/'.
+     */
+    mount?: string;
+    /**
+     * Priority for route conflict resolution. Higher values win when multiple
+     * pods register the same URL path. User-site routes always take precedence
+     * regardless of priority. Defaults to 0.
+     */
+    priority?: number;
+    /** Absolute path to the pod's routes/ directory. */
+    routesDir?: string;
+    /** Absolute path(s) to the pod's elements/ directory(s). */
+    elementsDirs?: string[];
+    /** Absolute path to the pod's bundles/ directory. */
+    bundlesDir?: string;
+    /** Absolute path to the pod's collections/ directory (root-cms only). */
+    collectionsDir?: string;
+    /** Absolute path to the pod's translations/ directory. */
+    translationsDir?: string;
+    /** Extra Vite plugins contributed by the pod. */
+    vitePlugins?: VitePlugin[];
+}
+export type PodFactory = (ctx: {
+    rootConfig: RootConfig;
+}) => Pod | Promise<Pod>;
+export interface PodConfig {
+    /** Whether the pod is enabled. Defaults to true. */
+    enabled?: boolean;
+    /** Override the pod's mount path. */
+    mount?: string;
+    /** Override the pod's priority. */
+    priority?: number;
+    /** Filter pod routes. */
+    routes?: {
+        exclude?: (string | RegExp)[];
+    };
+    /** Configure pod collections. */
+    collections?: {
+        exclude?: string[];
+        /** Rename collection ids, e.g. {Posts: 'DocsPosts'}. */
+        rename?: Record<string, string>;
+    };
+}
+/**
+ * Helper to define a pod with type-checking.
+ */
+export declare function definePod(pod: Pod): Pod;