@lexibase/rdx-types 1.0.0-beta.5 → 1.1.0

package/dist/config.d.ts

@@ -1,161 +1,257 @@
 import type { ComponentType } from 'react'
 import type { RdxPlugin } from './plugins'
 
-/** @deprecated Legacy development website config. New projects use RdxConfig. */
+/**
+ * Public configuration shared by defineConfig, the CLI, runtime and plugins.
+ *
+ * Set the site name once in metadata.applicationName. Live documentation always
+ * lives in docs/; the generated .rdx/ directory is not a customization API.
+ *
+ * @example
+ * export default defineConfig({
+ *   metadata: { applicationName: 'My documentation' },
+ *   navbar: { title: '' },
+ *   homepage: { enabled: false },
+ * })
+ */
 export type RDXConfig = {
-  search?: boolean
-  TOC?: boolean
-  /**
-   * The title of the documentation site.
-   * Displayed in the navbar and browser tab.
-   *
-   */
-  title: string
-
   /**
-   * A short description of the project.
-   * Used for SEO and meta tags.
-   *
+   * Enable local documentation search in the navbar.
+   * Search uses the project's content sources; no external service is required.
+   * @defaultValue false
    */
-  description: string
-
+  search?: boolean
   /**
-   * The name of the author or organization.
-   * Can be shown in the metadata.
-   *
+   * Enable floating heading navigation on documentation pages.
+   * Hidden when a page has too few sections to navigate.
+   * @defaultValue false
    */
-  author: string
-
+  TOC?: boolean
   /**
-   * Path to the favicon file.
-   * Must be located at 'public/favicon.ico' by default.
-   *
+   * Default HTML and social-preview description of the project.
+   * This does not replace descriptions authored in documents or the homepage.
+   * @defaultValue ''
    */
-  favicon: string
-
+  description?: string
   /**
-   * The base URL where the documentation is hosted.
-   * Used for generating canonical links and metadata.
-   *
+   * HTML document language, such as 'en' or 'pt-BR'.
+   * This does not automatically translate the interface or documentation.
+   * @defaultValue 'en'
    */
-  url: string
-
+  lang?: string
+  /** Site identity and SEO options. applicationName is required. */
+  metadata: RdxMetadata
+  /** Optional landing page. Disabled by default; '/' then redirects to '/docs'. */
+  homepage?: RdxHomepage
   /**
-   * Theme configuration options.
-   * If omitted, the default theme is 'system'
-   *
+   * Activated plugin objects, returned by their factories, e.g. versioning().
+   * Installing a package alone does not activate it. Hooks run in this order.
+   * @defaultValue []
    */
+  plugins?: RdxPlugin[]
+  /** Theme preferences for the shared RDX interface. */
   theme?: {
     /**
-     * The default theme to apply on first load.
-     * Accepted values: 'system', 'dark', or 'light'
-     *
+     * Theme used on first visit, before the user chooses a preference.
+     * 'system' follows the operating system's color preference.
+     * @defaultValue 'system'
      */
-    defaultTheme: string
+    defaultTheme?: 'system' | 'dark' | 'light'
   }
-
-  /**
-   * Navbar configurations options.
-   *
-   */
-  navbar: {
+  /** Logo, optional label and action buttons in the shared navbar. */
+  navbar?: {
     /**
-     * Title displayed next to the logo in the navbar.
-     * Leave empty to show only the logo.
-     *
+     * Text beside the logo. Empty or omitted shows only the logo.
+     * This does not change metadata.applicationName or browser titles.
+     * @defaultValue ''
      */
     title?: string
-
     /**
-     * This logo component is injected via `rdx.config.ts` and must be a valid React component.
-     * It should accept at least a `className` prop for styling purposes.
-     * Consumers of the design system can override the default logo by providing their own component,
-     * such as an inline SVG or image-based logo, allowing full customization of branding.
-     *
-     */
-    logo: ComponentType<{ className?: string }>
-
-    /**
-     * Configuration for navbar action buttons
-     *
+     * Imported React component accepting an optional className for styling.
+     * Pass the component itself, not JSX or an image path. Defaults to the RDX logo.
+     * @example
+     * logo: MyLogo
      */
+    logo?: ComponentType<{ className?: string }>
+    /** Optional GitHub link and theme toggle. Omitted actions remain hidden. */
     actions?: {
-      /**
-       * Configuration for github button
-       *
-       */
+      /** Show the system/light/dark theme switcher in the navbar. */
+      showToggleMode?: boolean
+      /** Optional repository link. Both visibility and URL must be specified. */
       github?: {
-        /**
-         * Whether to show the GitHub button in the navbar.
-         *
-         */
+        /** Whether the repository action is displayed. */
         visible: boolean
         /**
-         * URL of the GitHub repository.
-         * Used as the target for the GitHub button.
-         *
+         * Absolute HTTP(S) repository URL, or '#' as a temporary placeholder.
+         * Real links open in a new tab; the placeholder stays in the current tab.
          */
         url: string
       }
-
-      /**
-       * Whether to display the theme toggle (system/dark/light) in the navbar.
-       *
-       */
-      showToggleMode?: boolean
     }
   }
 }
 
-/** Public configuration shared by the CLI, runtime, and plugins. */
+/** Options for the built-in landing page or a project-owned home.tsx component. */
 export type RdxHomepage = {
+  /**
+   * Show a homepage at '/'. When false or omitted, '/' redirects to '/docs'.
+   * @defaultValue false
+   */
   enabled?: boolean
-  /** Custom project-owned homepage, e.g. import Home from './home'. */
+  /**
+   * Imported React component that owns the homepage body.
+   * The shared navbar remains; built-in title, description and buttons are not
+   * injected into this component. Used only when enabled is true.
+   * @example
+   * component: Home // import Home from './home'
+   */
   component?: ComponentType
+  /** Built-in homepage heading. Defaults to metadata.applicationName. */
   title?: string
+  /** Optional text below the built-in heading; omitted means no description. */
   description?: string
-  buttons?: { label: string; href: string }[]
+  /** Buttons below the built-in description. The first button is primary. */
+  buttons?: {
+    /** Visible button text and accessible name; must not be empty. */
+    label: string
+    /** Root-relative path or absolute HTTP(S) URL, e.g. '/docs/init/intro'. */
+    href: string
+  }[]
 }
 
-export type RdxConfig = {
-  /** Local documentation search. Defaults to false. */
-  search?: boolean
-  /** Floating table of contents for documentation pages. Defaults to false. */
-  TOC?: boolean
-  title: string
-  description?: string
-  lang?: string
-  docsDir?: string
-  homepage?: RdxHomepage
-  plugins?: RdxPlugin[]
-  theme?: {
-    defaultTheme?: 'system' | 'dark' | 'light'
+/**
+ * Site identity and portable Next.js metadata, translated by the RDX runtime.
+ * Root-relative asset URLs refer to files the project owns in public/.
+ * No asset files, deployment domain or global canonical URL are created here.
+ */
+export type RdxMetadata = {
+  /**
+   * Absolute HTTP(S) deployment URL used to resolve relative metadata URLs.
+   * Set this to the real public site URL when deploying; no domain is assumed.
+   * @example 'https://docs.example.com'
+   */
+  metadataBase?: string
+  /**
+   * Required, non-empty site name: the single source of shared branding.
+   * Supplies the browser title and page-title suffix, social-preview defaults,
+   * footer, accessible logo name and built-in homepage fallback.
+   */
+  applicationName: string
+  /**
+   * Starting year shown in the footer. The CLI fills the project creation year;
+   * replace it with an earlier founding year when appropriate. Must be a positive
+   * integer no later than the current year. Omit to show only the current year.
+   * Equal years are displayed once, e.g. 2026; earlier years form a range.
+   */
+  since?: number
+  /** Optional people or organizations credited in the document's metadata. */
+  authors?: {
+    /** Author or organization name; independent of the site's applicationName. */
+    name: string
+    /** Optional absolute HTTP(S) profile or organization URL. */
+    url?: string
+  }[]
+  /** Optional keywords emitted in the document's metadata. */
+  keywords?: string[]
+  /** Browser and device icons. Referenced files must exist in public/ or online. */
+  icons?: {
+    /**
+     * Browser tab icon URL, or a list of icons with explicit sizes and MIME types.
+     * @example '/favicon.ico'
+     */
+    icon?:
+      | string
+      | {
+          /** Root-relative asset path or absolute HTTP(S) image URL. */
+          url: string
+          /** Icon dimensions, such as '96x96', or 'any' for a scalable icon. */
+          sizes?: string
+          /** Image MIME type, such as 'image/png' or 'image/svg+xml'. */
+          type?: string
+        }[]
+    /**
+     * Traditional shortcut icon link for browser compatibility.
+     * @example '/favicon.ico'
+     */
+    shortcut?: string
+    /**
+     * Icon used when adding the site to the home screen on Apple devices.
+     * @example '/apple-touch-icon.png'
+     */
+    apple?: string
   }
-  navbar?: {
+  /**
+   * URL of an existing web app manifest describing the app's name, icons, etc.
+   * RDX only emits the link; it does not generate the manifest or enable a PWA.
+   * @example '/site.webmanifest'
+   */
+  manifest?: string
+  /** Optional crawler directives; these do not protect content from access. */
+  robots?: {
+    /** Whether search engines are instructed to index the page. */
+    index?: boolean
+    /** Whether search engines are instructed to follow links on the page. */
+    follow?: boolean
+  }
+  /** Optional Open Graph link previews. No fixed URL is applied to every page. */
+  openGraph?: {
+    /** Preview title override; defaults to metadata.applicationName. */
     title?: string
-    logo?: ComponentType<{ className?: string }>
-    actions?: {
-      showToggleMode?: boolean
-      github?: {
-        visible: boolean
-        url: string
-      }
-    }
+    /** Preview description override; defaults to the root description. */
+    description?: string
+    /** Optional site name shown by platforms that support it. */
+    siteName?: string
+    /** Open Graph locale, e.g. 'pt_BR' (underscore), unlike HTML lang 'pt-BR'. */
+    locale?: string
+    /** Supported Open Graph content type for the documentation site. */
+    type?: 'website'
+    /** Preview images. Relative URLs are resolved against metadataBase. */
+    images?: {
+      /** Root-relative asset path or absolute HTTP(S) image URL. */
+      url: string
+      /** Actual image width in pixels; a positive integer. */
+      width?: number
+      /** Actual image height in pixels; a positive integer. */
+      height?: number
+      /** Accessible description of the image. */
+      alt?: string
+    }[]
+  }
+  /** Optional Twitter/X card metadata. */
+  twitter?: {
+    /** Text-oriented summary or a large-image preview card. */
+    card?: 'summary' | 'summary_large_image'
+    /** Card title override; defaults to metadata.applicationName. */
+    title?: string
+    /** Card description override; defaults to the root description. */
+    description?: string
+    /** Account associated with the site, usually '@account'. */
+    site?: string
+    /** Account credited as the creator, usually '@account'. */
+    creator?: string
+    /** Image URLs; root-relative paths are resolved against metadataBase. */
+    images?: string[]
   }
 }
 
-/** Compatibility alias for projects created by the first beta. */
-export type RdxRuntimeConfig = RdxConfig
+/** Compatibility alias for the first beta; points to the same RDXConfig contract. */
+export type RdxRuntimeConfig = RDXConfig
 
+/** Internal configuration after validation and application of RDX defaults. */
 export type ResolvedRdxConfig = Omit<
-  RdxConfig,
-  'description' | 'lang' | 'docsDir' | 'theme' | 'plugins' | 'TOC' | 'search'
+  RDXConfig,
+  'description' | 'lang' | 'theme' | 'plugins' | 'TOC' | 'search'
 > & {
+  /** Resolved local search activation. */
   search: boolean
+  /** Resolved floating heading navigation activation. */
   TOC: boolean
+  /** Resolved site description; empty when not provided. */
   description: string
+  /** Resolved HTML language; 'en' when not provided. */
   lang: string
-  docsDir: string
+  /** Resolved initial theme preference. */
   theme: { defaultTheme: 'system' | 'dark' | 'light' }
+  /** Activated plugins, in declaration order. */
   plugins: RdxPlugin[]
 }

package/dist/index.d.ts

@@ -2,8 +2,8 @@ export { VersionsRaw, MDXLoader, DocLink, DocCategory } from './loaders'
 export { RdxSearchEntry, RdxSearchIndex } from './search'
 export {
   RDXConfig,
-  RdxConfig,
   RdxHomepage,
+  RdxMetadata,
   RdxRuntimeConfig,
   ResolvedRdxConfig,
 } from './config'

package/dist/plugins.d.ts

@@ -28,9 +28,9 @@ export type RdxPlugin = {
   setup?: (
     context: RdxPluginContext
   ) =>
-    | { sources?: RdxContentSource[] }
+    | { sources?: RdxContentSource[]; runtimeFiles?: string[] }
     | void
-    | Promise<{ sources?: RdxContentSource[] } | void>
+    | Promise<{ sources?: RdxContentSource[]; runtimeFiles?: string[] } | void>
   commands?: RdxPluginCommand[]
 }
 
@@ -39,4 +39,6 @@ export type RdxProject = {
   config: ResolvedRdxConfig
   sources: RdxContentSource[]
   commands: RdxPluginCommand[]
+  /** Project-relative files plugins need when serving deployed documentation. */
+  runtimeFiles: string[]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexibase/rdx-types",
-  "version": "1.0.0-beta.5",
+  "version": "1.1.0",
   "license": "MIT",
   "description": "Shared TypeScript types for RDX documentation projects.",
   "types": "./dist/index.d.ts",
@@ -32,7 +32,11 @@
     "@types/react": "19.3.0",
     "@rdx/typescript-config": "1.0.0"
   },
+  "engines": {
+    "node": "^22.18.0 || ^24.11.0"
+  },
   "scripts": {
+    "dev": "node ./build.mjs --watch",
     "build": "node ./build.mjs",
     "check-types": "tsc --noEmit"
   }