@shadow-shard-tools/docs-core 1.0.17 → 1.0.19

package/README.md

@@ -2,18 +2,16 @@
 Core runtime for the Shadow Shard Tools documentation stack. It gathers the shared themes, configuration objects, navigation helpers, typed content models, and browser-friendly utilities relied on by the site and generator projects.
 
 ## Contents
-- `configs`: Tailwind-friendly theme wiring plus code-language metadata (`CODE_LANGUAGE_CONFIG`, `stylesConfig`).
+- `configs`: Tailwind-friendly theme wiring plus code-language metadata (`CODE_LANGUAGE_CONFIG`).
 - `data`: File-system drivers for loading doc versions, category trees, and item payloads (`loadVersions`, `loadVersionData`, `buildTree`, etc.).
-- `themes`: Prebuilt light/dark `StyleTheme` definitions used by the Tailwind bridge.
+- `themes`: Prebuilt `StyleTheme` presets (currently `default`) used by the Tailwind bridge.
 - `types`: Source-of-truth TypeScript contracts for doc content, theme structures, and provider interfaces.
 - `utilities`: DOM, validation, string, and file helpers that the site and exporters share (e.g. `slugify`, `withBasePath`, `isValidImageUrl`).
 
 ## Usage
 ```ts
 import {
-  darkTheme,
-  lightTheme,
-  stylesConfig,
+  defaultTheme,
   loadVersions,
   loadVersionData,
   slugify,
@@ -25,6 +23,88 @@ import {
 import { CODE_LANGUAGE_CONFIG } from "@shadow-shard-tools/docs-core/configs/index.js";
 ```
 Everything ships as native ESM with TypeScript declarations in `dist/`. Install with `npm install @shadow-shard-tools/docs-core` (or link locally) and cherry-pick the helpers and contracts you need.
+CommonJS consumers can `require` the same subpaths via the conditional exports (built into `dist/cjs`).
+
+## API map (common imports)
+| Domain | Import from | Common exports |
+| --- | --- | --- |
+| Configs | `@shadow-shard-tools/docs-core/configs` | `loadSstDocsConfig`, `buildClientVisibleConfig`, `serializeClientConfigForBrowser`, `exposeClientConfig`, `readClientConfig`, `CODE_LANGUAGE_CONFIG` |
+| Data | `@shadow-shard-tools/docs-core/data` | `loadVersions`, `loadVersionData`, `buildTree`, `FsDataProvider`, `HttpDataProvider` |
+| Themes | `@shadow-shard-tools/docs-core/themes` | `defaultTheme`, `getThemePreset`, `AVAILABLE_THEME_PRESET_NAMES`, `StyleTheme` |
+| Utilities | `@shadow-shard-tools/docs-core/utilities` | `slugify`, `withBasePath`, `normalizeSystemPath`, `isValidImageUrl`, `createLogger` |
+| Types | `@shadow-shard-tools/docs-core/types` | `Content`, `Version`, `StyleTheme`, `SstDocsConfigFile`, `ResolvedSstDocsConfig`, `ClientVisibleSstDocsConfig` |
+
+## Quickstart recipes
+### Load config and expose client config
+```ts
+import {
+  buildClientVisibleConfig,
+  exposeClientConfig,
+  loadSstDocsConfig,
+  readClientConfig,
+  serializeClientConfigForBrowser,
+} from "@shadow-shard-tools/docs-core/configs";
+
+const config = await loadSstDocsConfig();
+const clientConfig = buildClientVisibleConfig(config);
+
+// Server-side: embed into HTML (pretty for readability while debugging)
+const clientScript = serializeClientConfigForBrowser(clientConfig, { pretty: true });
+// -> <script>{clientScript}</script>
+
+// Browser-side: attach and read from the global name (__SST_DOCS_CONFIG__ by default)
+exposeClientConfig(clientConfig);
+const cfg = readClientConfig();
+```
+
+### Load docs from FS/HTTP and build a tree
+```ts
+import path from "node:path";
+import {
+  FsDataProvider,
+  HttpDataProvider,
+  loadVersionData,
+  loadVersions,
+} from "@shadow-shard-tools/docs-core/data";
+
+// Local filesystem
+const fsProvider = new FsDataProvider();
+const dataRoot = path.resolve("./public/SST-Docs/data");
+const versions = await loadVersions(fsProvider, dataRoot);
+const versionRoot = `${dataRoot}/${versions[0]?.version ?? "current"}`;
+const { tree, items, standaloneDocs } = await loadVersionData(fsProvider, versionRoot);
+
+// Remote HTTP (e.g., CDN-hosted data)
+const httpProvider = new HttpDataProvider();
+const remoteRoot = "https://cdn.example.com/SST-Docs/data";
+const remoteVersions = await loadVersions(httpProvider, remoteRoot);
+const remoteVersionRoot = `${remoteRoot}/${remoteVersions[0]?.version ?? "current"}`;
+const { tree: remoteTree } = await loadVersionData(httpProvider, remoteVersionRoot);
+```
+
+### Config example
+Create `sst-docs.config.json` in your project root:
+```json
+{
+  "FS_DATA_PATH": "./public/SST-Docs/data",
+  "HEADER_BRANDING": {
+    "logoText": "SST Docs"
+  },
+  "HTML_GENERATOR_SETTINGS": {
+    "OUTPUT_DIRECTORY": "./dist/html",
+    "THEME": "default",
+    "SEPARATE_BUILD_FOR_HTML_GENERATOR": false
+  }
+}
+```
+Load and expose a browser-friendly subset:
+```ts
+import { loadSstDocsConfig, buildClientVisibleConfig, serializeClientConfigForBrowser } from "@shadow-shard-tools/docs-core/configs";
+
+const config = await loadSstDocsConfig();
+const clientConfig = buildClientVisibleConfig(config);
+const script = serializeClientConfigForBrowser(clientConfig); // inject into HTML to populate window.__SST_DOCS_CONFIG__
+```
 
 ## Development
 ```bash

package/dist/cjs/configs/clientConfig.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CLIENT_CONFIG_GLOBAL = void 0;
+exports.buildClientVisibleConfig = buildClientVisibleConfig;
+exports.serializeClientConfigForBrowser = serializeClientConfigForBrowser;
+exports.exposeClientConfig = exposeClientConfig;
+exports.readClientConfig = readClientConfig;
+const zod_1 = require("zod");
+const styleThemeSchema_js_1 = require("../themes/styleThemeSchema.js");
+exports.DEFAULT_CLIENT_CONFIG_GLOBAL = "__SST_DOCS_CONFIG__";
+const headerBrandingSchema = zod_1.z
+    .object({
+    logoSrc: zod_1.z.string().optional(),
+    logoAlt: zod_1.z.string().optional(),
+    logoText: zod_1.z.string().optional(),
+})
+    .strict()
+    .optional()
+    .default({});
+const clientConfigSchema = zod_1.z
+    .object({
+    PUBLIC_DATA_PATH: zod_1.z.string(),
+    HEADER_BRANDING: headerBrandingSchema,
+    HTML_GENERATOR_THEME: styleThemeSchema_js_1.styleThemeSchema.optional(),
+})
+    .strict();
+function buildClientVisibleConfig(config) {
+    return {
+        PUBLIC_DATA_PATH: config.PUBLIC_DATA_PATH,
+        HEADER_BRANDING: config.HEADER_BRANDING,
+        HTML_GENERATOR_THEME: config.HTML_GENERATOR_SETTINGS?.THEME,
+    };
+}
+function serializeClientConfigForBrowser(source, options) {
+    const payload = normalizeAndValidateClientConfigSource(source);
+    const globalName = options?.globalName ?? exports.DEFAULT_CLIENT_CONFIG_GLOBAL;
+    const spacing = options?.pretty ? 2 : undefined;
+    return `window.${globalName} = ${JSON.stringify(payload, null, spacing)};`;
+}
+function exposeClientConfig(source, options) {
+    const payload = normalizeAndValidateClientConfigSource(source);
+    const target = options?.target ??
+        globalThis;
+    if (!target) {
+        throw new Error("Unable to expose client config: no target global object was provided.");
+    }
+    const globalName = options?.globalName ?? exports.DEFAULT_CLIENT_CONFIG_GLOBAL;
+    target[globalName] = payload;
+    return payload;
+}
+function readClientConfig(globalName = exports.DEFAULT_CLIENT_CONFIG_GLOBAL) {
+    const globalObject = globalThis;
+    if (!globalObject) {
+        throw new Error("globalThis is not available in the current environment.");
+    }
+    const value = globalObject[globalName];
+    return assertClientConfig(value, globalName);
+}
+function normalizeAndValidateClientConfigSource(source) {
+    const normalized = isClientConfigShape(source)
+        ? source
+        : buildClientVisibleConfig(source);
+    return assertClientConfig(normalized);
+}
+function assertClientConfig(value, globalName = exports.DEFAULT_CLIENT_CONFIG_GLOBAL) {
+    const parsed = clientConfigSchema.safeParse(value);
+    if (parsed.success)
+        return parsed.data;
+    const message = parsed.error.issues
+        .map((issue) => `${issue.path.join(".") || "config"}: ${issue.message}`)
+        .join("; ");
+    throw new Error(`Client config "${globalName}" is missing or malformed on globalThis. ${message}`);
+}
+function isClientConfigShape(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    return clientConfigSchema.safeParse(value).success;
+}

package/dist/cjs/configs/codeLanguagesConfig.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CODE_LANGUAGE_CONFIG = void 0;
+exports.CODE_LANGUAGE_CONFIG = {
+    javascript: { name: "JavaScript", ext: "js" },
+    typescript: { name: "TypeScript", ext: "ts" },
+    python: { name: "Python", ext: "py" },
+    java: { name: "Java", ext: "java" },
+    csharp: { name: "C#", ext: "cs" },
+    cpp: { name: "C++", ext: "cpp" },
+    c: { name: "C", ext: "c" },
+    php: { name: "PHP", ext: "php" },
+    ruby: { name: "Ruby", ext: "rb" },
+    go: { name: "Go", ext: "go" },
+    rust: { name: "Rust", ext: "rs" },
+    swift: { name: "Swift", ext: "swift" },
+    kotlin: { name: "Kotlin", ext: "kt" },
+    scala: { name: "Scala", ext: "scala" },
+    html: { name: "HTML", ext: "html" },
+    css: { name: "CSS", ext: "css" },
+    scss: { name: "SCSS", ext: "scss" },
+    sass: { name: "Sass", ext: "sass" },
+    less: { name: "Less", ext: "less" },
+    json: { name: "JSON", ext: "json" },
+    xml: { name: "XML", ext: "xml" },
+    yaml: { name: "YAML", ext: "yml" },
+    toml: { name: "TOML", ext: "toml" },
+    sql: { name: "SQL", ext: "sql" },
+    bash: { name: "Bash", ext: "sh" },
+    powershell: { name: "PowerShell", ext: "ps1" },
+    dockerfile: { name: "Dockerfile", ext: "dockerfile" },
+    markdown: { name: "Markdown", ext: "md" },
+    latex: { name: "LaTeX", ext: "tex" },
+    plaintext: { name: "Plain Text", ext: "txt" },
+    text: { name: "Text", ext: "txt" },
+};

package/dist/cjs/configs/index.browser.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeClientConfigForBrowser = exports.readClientConfig = exports.exposeClientConfig = exports.DEFAULT_CLIENT_CONFIG_GLOBAL = exports.buildClientVisibleConfig = exports.SST_DOCS_CONFIG_FILENAME = exports.SstDocsConfigError = exports.resolvePublicDataPath = exports.derivePublicDataPath = exports.CODE_LANGUAGE_CONFIG = void 0;
+var codeLanguagesConfig_js_1 = require("./codeLanguagesConfig.js");
+Object.defineProperty(exports, "CODE_LANGUAGE_CONFIG", { enumerable: true, get: function () { return codeLanguagesConfig_js_1.CODE_LANGUAGE_CONFIG; } });
+var sstDocsConfigShared_js_1 = require("./sstDocsConfigShared.js");
+Object.defineProperty(exports, "derivePublicDataPath", { enumerable: true, get: function () { return sstDocsConfigShared_js_1.derivePublicDataPath; } });
+Object.defineProperty(exports, "resolvePublicDataPath", { enumerable: true, get: function () { return sstDocsConfigShared_js_1.resolvePublicDataPath; } });
+Object.defineProperty(exports, "SstDocsConfigError", { enumerable: true, get: function () { return sstDocsConfigShared_js_1.SstDocsConfigError; } });
+Object.defineProperty(exports, "SST_DOCS_CONFIG_FILENAME", { enumerable: true, get: function () { return sstDocsConfigShared_js_1.SST_DOCS_CONFIG_FILENAME; } });
+var clientConfig_js_1 = require("./clientConfig.js");
+Object.defineProperty(exports, "buildClientVisibleConfig", { enumerable: true, get: function () { return clientConfig_js_1.buildClientVisibleConfig; } });
+Object.defineProperty(exports, "DEFAULT_CLIENT_CONFIG_GLOBAL", { enumerable: true, get: function () { return clientConfig_js_1.DEFAULT_CLIENT_CONFIG_GLOBAL; } });
+Object.defineProperty(exports, "exposeClientConfig", { enumerable: true, get: function () { return clientConfig_js_1.exposeClientConfig; } });
+Object.defineProperty(exports, "readClientConfig", { enumerable: true, get: function () { return clientConfig_js_1.readClientConfig; } });
+Object.defineProperty(exports, "serializeClientConfigForBrowser", { enumerable: true, get: function () { return clientConfig_js_1.serializeClientConfigForBrowser; } });

package/dist/cjs/configs/index.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeClientConfigForBrowser = exports.readClientConfig = exports.exposeClientConfig = exports.DEFAULT_CLIENT_CONFIG_GLOBAL = exports.buildClientVisibleConfig = exports.SST_DOCS_CONFIG_FILENAME = exports.SstDocsConfigError = exports.resolvePublicDataPath = exports.derivePublicDataPath = exports.loadSstDocsConfigFromSync = exports.loadSstDocsConfigSync = exports.loadSstDocsConfigFrom = exports.loadSstDocsConfig = exports.CODE_LANGUAGE_CONFIG = void 0;
+var codeLanguagesConfig_js_1 = require("./codeLanguagesConfig.js");
+Object.defineProperty(exports, "CODE_LANGUAGE_CONFIG", { enumerable: true, get: function () { return codeLanguagesConfig_js_1.CODE_LANGUAGE_CONFIG; } });
+var sstDocsConfig_js_1 = require("./sstDocsConfig.js");
+Object.defineProperty(exports, "loadSstDocsConfig", { enumerable: true, get: function () { return sstDocsConfig_js_1.loadSstDocsConfig; } });
+Object.defineProperty(exports, "loadSstDocsConfigFrom", { enumerable: true, get: function () { return sstDocsConfig_js_1.loadSstDocsConfigFrom; } });
+Object.defineProperty(exports, "loadSstDocsConfigSync", { enumerable: true, get: function () { return sstDocsConfig_js_1.loadSstDocsConfigSync; } });
+Object.defineProperty(exports, "loadSstDocsConfigFromSync", { enumerable: true, get: function () { return sstDocsConfig_js_1.loadSstDocsConfigFromSync; } });
+Object.defineProperty(exports, "derivePublicDataPath", { enumerable: true, get: function () { return sstDocsConfig_js_1.derivePublicDataPath; } });
+Object.defineProperty(exports, "resolvePublicDataPath", { enumerable: true, get: function () { return sstDocsConfig_js_1.resolvePublicDataPath; } });
+Object.defineProperty(exports, "SstDocsConfigError", { enumerable: true, get: function () { return sstDocsConfig_js_1.SstDocsConfigError; } });
+Object.defineProperty(exports, "SST_DOCS_CONFIG_FILENAME", { enumerable: true, get: function () { return sstDocsConfig_js_1.SST_DOCS_CONFIG_FILENAME; } });
+var clientConfig_js_1 = require("./clientConfig.js");
+Object.defineProperty(exports, "buildClientVisibleConfig", { enumerable: true, get: function () { return clientConfig_js_1.buildClientVisibleConfig; } });
+Object.defineProperty(exports, "DEFAULT_CLIENT_CONFIG_GLOBAL", { enumerable: true, get: function () { return clientConfig_js_1.DEFAULT_CLIENT_CONFIG_GLOBAL; } });
+Object.defineProperty(exports, "exposeClientConfig", { enumerable: true, get: function () { return clientConfig_js_1.exposeClientConfig; } });
+Object.defineProperty(exports, "readClientConfig", { enumerable: true, get: function () { return clientConfig_js_1.readClientConfig; } });
+Object.defineProperty(exports, "serializeClientConfigForBrowser", { enumerable: true, get: function () { return clientConfig_js_1.serializeClientConfigForBrowser; } });

package/dist/cjs/configs/sstDocsConfig.browser.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SstDocsConfigError = exports.SST_DOCS_CONFIG_FILENAME = exports.resolvePublicDataPath = exports.derivePublicDataPath = void 0;
+exports.loadSstDocsConfig = loadSstDocsConfig;
+exports.loadSstDocsConfigSync = loadSstDocsConfigSync;
+exports.loadSstDocsConfigFrom = loadSstDocsConfigFrom;
+exports.loadSstDocsConfigFromSync = loadSstDocsConfigFromSync;
+const sstDocsConfigShared_js_1 = require("./sstDocsConfigShared.js");
+Object.defineProperty(exports, "derivePublicDataPath", { enumerable: true, get: function () { return sstDocsConfigShared_js_1.derivePublicDataPath; } });
+Object.defineProperty(exports, "resolvePublicDataPath", { enumerable: true, get: function () { return sstDocsConfigShared_js_1.resolvePublicDataPath; } });
+Object.defineProperty(exports, "SST_DOCS_CONFIG_FILENAME", { enumerable: true, get: function () { return sstDocsConfigShared_js_1.SST_DOCS_CONFIG_FILENAME; } });
+Object.defineProperty(exports, "SstDocsConfigError", { enumerable: true, get: function () { return sstDocsConfigShared_js_1.SstDocsConfigError; } });
+function unsupported(method) {
+    throw new sstDocsConfigShared_js_1.SstDocsConfigError(`${method} is only available in a Node.js environment where the file system can be read.`);
+}
+async function loadSstDocsConfig(_configPath) {
+    return unsupported("loadSstDocsConfig");
+}
+function loadSstDocsConfigSync(_configPath) {
+    return unsupported("loadSstDocsConfigSync");
+}
+async function loadSstDocsConfigFrom(_configDir) {
+    return unsupported("loadSstDocsConfigFrom");
+}
+function loadSstDocsConfigFromSync(_configDir) {
+    return unsupported("loadSstDocsConfigFromSync");
+}

package/dist/cjs/configs/sstDocsConfig.js

@@ -0,0 +1,88 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SstDocsConfigError = exports.SST_DOCS_CONFIG_FILENAME = exports.resolvePublicDataPath = exports.derivePublicDataPath = void 0;
+exports.loadSstDocsConfig = loadSstDocsConfig;
+exports.loadSstDocsConfigSync = loadSstDocsConfigSync;
+exports.loadSstDocsConfigFrom = loadSstDocsConfigFrom;
+exports.loadSstDocsConfigFromSync = loadSstDocsConfigFromSync;
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const app_root_path_1 = __importDefault(require("app-root-path"));
+const sstDocsConfigShared_js_1 = require("./sstDocsConfigShared.js");
+Object.defineProperty(exports, "derivePublicDataPath", { enumerable: true, get: function () { return sstDocsConfigShared_js_1.derivePublicDataPath; } });
+Object.defineProperty(exports, "resolvePublicDataPath", { enumerable: true, get: function () { return sstDocsConfigShared_js_1.resolvePublicDataPath; } });
+Object.defineProperty(exports, "SST_DOCS_CONFIG_FILENAME", { enumerable: true, get: function () { return sstDocsConfigShared_js_1.SST_DOCS_CONFIG_FILENAME; } });
+Object.defineProperty(exports, "SstDocsConfigError", { enumerable: true, get: function () { return sstDocsConfigShared_js_1.SstDocsConfigError; } });
+const APP_ROOT = app_root_path_1.default.path;
+async function loadSstDocsConfig(configPath) {
+    const { path: finalPath, contents } = await readConfigFile(configPath);
+    return (0, sstDocsConfigShared_js_1.parseConfigContents)(contents, finalPath);
+}
+function loadSstDocsConfigSync(configPath) {
+    const { path: finalPath, contents } = readConfigFileSync(configPath);
+    return (0, sstDocsConfigShared_js_1.parseConfigContents)(contents, finalPath);
+}
+async function loadSstDocsConfigFrom(configDir) {
+    const fullPath = (0, node_path_1.resolve)(configDir, sstDocsConfigShared_js_1.SST_DOCS_CONFIG_FILENAME);
+    return loadSstDocsConfig(fullPath);
+}
+function loadSstDocsConfigFromSync(configDir) {
+    const fullPath = (0, node_path_1.resolve)(configDir, sstDocsConfigShared_js_1.SST_DOCS_CONFIG_FILENAME);
+    return loadSstDocsConfigSync(fullPath);
+}
+async function readConfigFile(configPath) {
+    const searchPaths = getConfigSearchPaths(configPath);
+    const attempted = [];
+    for (const candidate of searchPaths) {
+        attempted.push(candidate);
+        try {
+            const contents = await (0, promises_1.readFile)(candidate, "utf-8");
+            return { path: candidate, contents };
+        }
+        catch (error) {
+            const err = error;
+            if (err.code === "ENOENT" || err.code === "EISDIR") {
+                continue;
+            }
+            throw new sstDocsConfigShared_js_1.SstDocsConfigError(`Failed to read ${sstDocsConfigShared_js_1.SST_DOCS_CONFIG_FILENAME} at ${candidate}: ${err.message}`);
+        }
+    }
+    throw new sstDocsConfigShared_js_1.SstDocsConfigError(`Unable to locate ${sstDocsConfigShared_js_1.SST_DOCS_CONFIG_FILENAME}. Tried: ${attempted.join(", ")}`);
+}
+function readConfigFileSync(configPath) {
+    const searchPaths = getConfigSearchPaths(configPath);
+    const attempted = [];
+    for (const candidate of searchPaths) {
+        attempted.push(candidate);
+        try {
+            const contents = (0, node_fs_1.readFileSync)(candidate, "utf-8");
+            return { path: candidate, contents };
+        }
+        catch (error) {
+            const err = error;
+            if (err.code === "ENOENT" || err.code === "EISDIR") {
+                continue;
+            }
+            throw new sstDocsConfigShared_js_1.SstDocsConfigError(`Failed to read ${sstDocsConfigShared_js_1.SST_DOCS_CONFIG_FILENAME} at ${candidate}: ${err.message}`);
+        }
+    }
+    throw new sstDocsConfigShared_js_1.SstDocsConfigError(`Unable to locate ${sstDocsConfigShared_js_1.SST_DOCS_CONFIG_FILENAME}. Tried: ${attempted.join(", ")}`);
+}
+function getConfigSearchPaths(configPath) {
+    const searchPaths = [];
+    if (configPath) {
+        const explicit = (0, node_path_1.resolve)(APP_ROOT, configPath);
+        searchPaths.push(explicit);
+        if (!explicit.endsWith(".json")) {
+            searchPaths.push((0, node_path_1.resolve)(explicit, sstDocsConfigShared_js_1.SST_DOCS_CONFIG_FILENAME));
+        }
+    }
+    else {
+        searchPaths.push((0, node_path_1.resolve)(APP_ROOT, sstDocsConfigShared_js_1.SST_DOCS_CONFIG_FILENAME));
+    }
+    return searchPaths;
+}

package/dist/cjs/configs/sstDocsConfigShared.js

@@ -0,0 +1,232 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SST_DOCS_CONFIG_REFERENCE = exports.SstDocsConfigError = exports.SST_DOCS_CONFIG_FILENAME = void 0;
+exports.parseConfigContents = parseConfigContents;
+exports.derivePublicDataPath = derivePublicDataPath;
+exports.resolvePublicDataPath = resolvePublicDataPath;
+const themeRegistry_js_1 = require("../themes/themeRegistry.js");
+const normalizeSystemPath_js_1 = require("../utilities/string/normalizeSystemPath.js");
+const zod_1 = require("zod");
+exports.SST_DOCS_CONFIG_FILENAME = "sst-docs.config.json";
+const DEFAULT_FS_DATA_PATH = "./public/SST-Docs/data";
+const DEFAULT_OUTPUT_DIRECTORY = "./dist/html";
+class SstDocsConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SstDocsConfigError";
+    }
+}
+exports.SstDocsConfigError = SstDocsConfigError;
+exports.SST_DOCS_CONFIG_REFERENCE = [
+    {
+        key: "FS_DATA_PATH",
+        type: "string",
+        required: true,
+        default: DEFAULT_FS_DATA_PATH,
+        description: "Absolute or project-relative path to the docs data root (contains versions.json).",
+    },
+    {
+        key: "HEADER_BRANDING.logoSrc",
+        type: "string",
+        required: false,
+        description: "Optional logo image path/URL shown in the header.",
+    },
+    {
+        key: "HEADER_BRANDING.logoAlt",
+        type: "string",
+        required: false,
+        description: "Optional alt text for the logo image.",
+    },
+    {
+        key: "HEADER_BRANDING.logoText",
+        type: "string",
+        required: false,
+        description: "Optional text fallback when no logo image is provided.",
+    },
+    {
+        key: "HTML_GENERATOR_SETTINGS.OUTPUT_DIRECTORY",
+        type: "string",
+        required: true,
+        default: DEFAULT_OUTPUT_DIRECTORY,
+        description: "Where the HTML generator writes the output bundle.",
+    },
+    {
+        key: "HTML_GENERATOR_SETTINGS.THEME",
+        type: "string",
+        required: true,
+        default: themeRegistry_js_1.DEFAULT_THEME_PRESET,
+        description: `Theme preset name. Options: ${themeRegistry_js_1.AVAILABLE_THEME_PRESET_NAMES.join(", ")}.`,
+    },
+    {
+        key: "HTML_GENERATOR_SETTINGS.SEPARATE_BUILD_FOR_HTML_GENERATOR",
+        type: "boolean",
+        required: false,
+        default: "false",
+        description: "Whether to run a separate build for the HTML generator.",
+    },
+];
+const optionalTrimmedString = zod_1.z
+    .string()
+    .trim()
+    .transform((value) => (value.length > 0 ? value : undefined))
+    .optional();
+const HeaderBrandingSchema = zod_1.z
+    .object({
+    logoSrc: optionalTrimmedString,
+    logoAlt: optionalTrimmedString,
+    logoText: optionalTrimmedString,
+})
+    .strict()
+    .transform((value) => value);
+const HtmlGeneratorSettingsSchema = zod_1.z
+    .object({
+    OUTPUT_DIRECTORY: zod_1.z
+        .string()
+        .trim()
+        .min(1, {
+        message: `Set HTML_GENERATOR_SETTINGS.OUTPUT_DIRECTORY (default: "${DEFAULT_OUTPUT_DIRECTORY}")`,
+    })
+        .transform((val) => (0, normalizeSystemPath_js_1.normalizeSystemPath)(val)),
+    THEME: zod_1.z
+        .string()
+        .trim()
+        .min(1, {
+        message: `Set HTML_GENERATOR_SETTINGS.THEME (default: "${themeRegistry_js_1.DEFAULT_THEME_PRESET}")`,
+    })
+        .transform((value, ctx) => {
+        const normalized = value.toLowerCase();
+        if (!(0, themeRegistry_js_1.isThemePresetName)(normalized)) {
+            const options = themeRegistry_js_1.AVAILABLE_THEME_PRESET_NAMES.join(", ");
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: `HTML_GENERATOR_SETTINGS.THEME must be one of: ${options} (default: "${themeRegistry_js_1.DEFAULT_THEME_PRESET}")`,
+            });
+            return zod_1.z.NEVER;
+        }
+        return cloneTheme((0, themeRegistry_js_1.getThemePreset)(normalized));
+    }),
+    SEPARATE_BUILD_FOR_HTML_GENERATOR: zod_1.z.boolean().default(false),
+})
+    .strict()
+    .transform((value) => value);
+const ConfigSchema = zod_1.z
+    .object({
+    FS_DATA_PATH: zod_1.z
+        .string()
+        .trim()
+        .min(1, {
+        message: `Provide FS_DATA_PATH (default: "${DEFAULT_FS_DATA_PATH}")`,
+    })
+        .transform((val) => (0, normalizeSystemPath_js_1.normalizeSystemPath)(val)),
+    HEADER_BRANDING: HeaderBrandingSchema.optional().transform((value) => value ?? {}),
+    HTML_GENERATOR_SETTINGS: HtmlGeneratorSettingsSchema.optional(),
+})
+    .strict();
+function parseConfigContents(contents, sourcePath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(contents);
+    }
+    catch (error) {
+        throw new SstDocsConfigError(`Failed to parse ${exports.SST_DOCS_CONFIG_FILENAME}: ${error.message}`);
+    }
+    const result = ConfigSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new SstDocsConfigError(formatConfigValidationError(sourcePath, result.error));
+    }
+    const resolved = result.data;
+    return {
+        FS_DATA_PATH: resolved.FS_DATA_PATH,
+        PUBLIC_DATA_PATH: derivePublicDataPath(resolved.FS_DATA_PATH),
+        HEADER_BRANDING: resolved.HEADER_BRANDING,
+        HTML_GENERATOR_SETTINGS: resolved.HTML_GENERATOR_SETTINGS,
+    };
+}
+function derivePublicDataPath(fsDataPath) {
+    const normalizedFsPath = (0, normalizeSystemPath_js_1.normalizeSystemPath)(fsDataPath.trim());
+    const posixPath = normalizePosixPath(normalizedFsPath || "/");
+    const segments = posixPath.split("/").filter(Boolean);
+    const publicIndex = segments.indexOf("public");
+    const publicSegments = publicIndex >= 0 ? segments.slice(publicIndex + 1) : segments;
+    if (publicSegments.length === 0) {
+        return "/";
+    }
+    const joined = `/${publicSegments.join("/")}`;
+    return joined.endsWith("/") ? joined : `${joined}/`;
+}
+function resolvePublicDataPath(baseUrl, config) {
+    const publicPath = typeof config === "string" ? config : config.PUBLIC_DATA_PATH;
+    const normalizedPublicPath = normalizePublicPath(publicPath);
+    if (!baseUrl || baseUrl.trim().length === 0) {
+        return normalizedPublicPath;
+    }
+    if (isAbsoluteUrl(baseUrl)) {
+        const url = new URL(baseUrl);
+        url.pathname = joinUrlPaths(url.pathname || "/", normalizedPublicPath);
+        return url.toString();
+    }
+    const parsedBase = new URL(baseUrl, "http://local.placeholder");
+    const joinedPath = joinUrlPaths(parsedBase.pathname || "/", normalizedPublicPath);
+    return `${joinedPath}${parsedBase.search}${parsedBase.hash}`;
+}
+function normalizePublicPath(value) {
+    const normalized = (0, normalizeSystemPath_js_1.normalizeSystemPath)(value.trim());
+    const posixPath = normalizePosixPath(normalized || "/");
+    const withLeading = posixPath.startsWith("/") ? posixPath : `/${posixPath}`;
+    return withLeading.endsWith("/") ? withLeading : `${withLeading}/`;
+}
+function joinUrlPaths(base, child) {
+    const normalizedBase = normalizePublicPath(base);
+    const normalizedChild = normalizePublicPath(child).replace(/^\/+/, "");
+    const joined = normalizePosixPath(`${normalizedBase}${normalizedChild ? `/${normalizedChild}` : ""}`);
+    return joined.endsWith("/") ? joined : `${joined}/`;
+}
+function isAbsoluteUrl(value) {
+    try {
+        new URL(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function cloneTheme(theme) {
+    return JSON.parse(JSON.stringify(theme));
+}
+function formatConfigValidationError(sourcePath, error) {
+    const lines = error.issues.map((issue) => {
+        const path = issue.path.join(".") || "config";
+        const defaultValue = defaultValueFor(path);
+        const hint = defaultValue ? ` (default: ${defaultValue})` : "";
+        return `${path}: ${issue.message}${hint}`;
+    });
+    return `Invalid configuration in ${sourcePath}:\n- ${lines.join("\n- ")}`;
+}
+function defaultValueFor(path) {
+    return exports.SST_DOCS_CONFIG_REFERENCE.find((entry) => entry.key === path)?.default;
+}
+function normalizePosixPath(value) {
+    const sanitized = value.replace(/\\/g, "/");
+    const hasLeadingSlash = sanitized.startsWith("/");
+    const parts = sanitized.split("/");
+    const stack = [];
+    for (const part of parts) {
+        if (!part || part === ".")
+            continue;
+        if (part === "..") {
+            if (stack.length > 0 && stack[stack.length - 1] !== "..") {
+                stack.pop();
+            }
+            else if (!hasLeadingSlash) {
+                stack.push("..");
+            }
+            continue;
+        }
+        stack.push(part);
+    }
+    const normalized = stack.join("/");
+    if (hasLeadingSlash) {
+        return `/${normalized}`;
+    }
+    return normalized || ".";
+}

package/dist/cjs/constants/alignmentClasses.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALIGNMENT_CLASSES = void 0;
+exports.ALIGNMENT_CLASSES = {
+    left: {
+        text: "text-left",
+        container: "mr-auto",
+    },
+    center: {
+        text: "text-center",
+        container: "mx-auto",
+    },
+    right: {
+        text: "text-right",
+        container: "ml-auto",
+    },
+};

package/dist/cjs/constants/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SPACING_CLASSES = exports.ALIGNMENT_CLASSES = void 0;
+var alignmentClasses_js_1 = require("./alignmentClasses.js");
+Object.defineProperty(exports, "ALIGNMENT_CLASSES", { enumerable: true, get: function () { return alignmentClasses_js_1.ALIGNMENT_CLASSES; } });
+var spacingClasses_js_1 = require("./spacingClasses.js");
+Object.defineProperty(exports, "SPACING_CLASSES", { enumerable: true, get: function () { return spacingClasses_js_1.SPACING_CLASSES; } });

package/dist/cjs/constants/spacingClasses.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SPACING_CLASSES = void 0;
+exports.SPACING_CLASSES = {
+    none: "",
+    small: "mb-4",
+    medium: "mb-6",
+    large: "mb-8",
+};