npm package: @shadow-shard-tools/docs-core
Description: Shared configs, types, and utilities for SST Docs modules and applications.
Latest version: 1.0.1

# SST Docs Core
Core runtime for the Shadow Shard Tools documentation stack. This package ships shared themes, configuration helpers, navigation utilities, typed content models, and browser-friendly helpers used by the site and generator projects.

## What�s inside
- `configs`: Tailwind-friendly theme wiring plus code-language metadata (`CODE_LANGUAGE_CONFIG`).
- `data`: File-system/HTTP drivers for loading doc versions, trees, and item payloads (`loadVersions`, `loadVersionData`, `buildTree`, etc.).
- `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 shared by the site and exporters (e.g. `slugify`, `withBasePath`, `isValidImageUrl`).

## Install
```bash
npm install @shadow-shard-tools/docs-core
```

## Basic usage
```ts
import {
  defaultTheme,
  loadVersions,
  loadVersionData,
  slugify,
  type Content,
  type Version,
} from "@shadow-shard-tools/docs-core";

// Or import a focused module:
import { CODE_LANGUAGE_CONFIG } from "@shadow-shard-tools/docs-core/configs/index.js";
```
Everything ships as native ESM with TypeScript declarations in `dist/`. 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. Set `PRODUCT_VERSIONING` to `true` when your data root contains product subfolders (see below); leave it `false` to use the single-product layout.
```json
{
  "FS_DATA_PATH": "./public/SST-Docs/data",
  "PRODUCT_VERSIONING": true,
  "HEADER_BRANDING": {
    "logoText": "SST Docs"
  },
  "HTML_GENERATOR_SETTINGS": {
    "OUTPUT_DIRECTORY": "./dist/html",
    "THEME": "default",
    "SEPARATE_BUILD_FOR_HTML_GENERATOR": false
  }
}
```
When product versioning is enabled, place a `products.json` file at the data root and nest per-product versions under each product folder, e.g. `public/SST-Docs/data/Product_1/versions.json` and `public/SST-Docs/data/Product_1/v1.0/index.json`.

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
npm install
npm run build
```
`tsc` compiles everything under `src/` into `dist/` with source and declaration maps. Build before publishing or updating dependents so the published artifacts stay in sync.