@mandolin/jsdoc-theme-hia 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## 0.1.0 - 2026-07-05
+
+### Added
+
+- Independent JSDoc theme entry.
+- Standard doclet rendering for common JSDoc kinds.
+- Navigation, search data and local filtering.
+- Parameters, returns, properties and examples rendering.
+- Source references with file links, line links and source preview.
+- Runtime language switching from `doclet.hia.i18n`.
+- Per-locale HTML output and `i18n-index.json`.
+- Release checklist and third-party notices.
+- Field-level multilingual rendering from `doclet.hia.i18n.fields`.
+- Separate `Source` and `Source References` sections for definition source and explicit source references.
+- Relative `Defined in` paths from HIA source metadata.
+- Built-in English and Simplified Chinese UI labels with runtime switching support.
+- Collapsible doclet cards and documentation sections.
+- Theme UI options for collapse defaults and language control mode.
+- Optional language select control for projects with more locales.
+- Built-in theme skins: `classic`, `lumen` and `graphite`.
+- Configurable source code display defaults and runtime controls.
+- Release metadata declares public scoped publishing and records the publish strategy/checklist.
+
+### Notes
+
+- This is an early public package for standalone JSDoc theme usage and HIA metadata experiments.
+- Layout and API are still expected to evolve.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HIA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,176 @@
+# @mandolin/jsdoc-theme-hia
+
+Independent HIA theme for JSDoc.
+
+`@mandolin/jsdoc-theme-hia` renders JSDoc output as a compact API documentation site with navigation, search data, source references, source preview and multilingual display support. It is designed to work as a normal JSDoc theme, and can also consume metadata produced by `@mandolin/jsdoc-plugin-hia-sys`.
+
+GitHub: <https://github.com/mandolin/jsdoc-theme-hia>
+
+## Features
+
+- Renders common JSDoc doclet kinds: module, class, function, member, constant and typedef.
+- Displays function signatures, params, returns, properties and examples.
+- Provides sidebar navigation and local search data.
+- Reads `doclet.hia.source.definedIn` and `doclet.hia.source.primaryBlock` for definition source links and previews.
+- Reads `doclet.hia.source.references` for explicit source references such as `@coderef`.
+- Reads `doclet.hia.i18n.fields` for field-level multilingual descriptions.
+- Includes built-in English and Simplified Chinese UI labels for runtime language switching and per-locale HTML output.
+- Provides collapsible doclet cards and collapsible sections for params, returns, examples, source and metadata.
+- Supports button or select language controls, with an automatic select mode for larger locale lists.
+- Provides built-in theme skins: `classic`, `lumen` and `graphite`.
+- Provides configurable source code display controls for font, size, line height, tab size and wrapping.
+- Writes `search-index.json`, `i18n-index.json` and `hia-metadata.json`.
+- Includes basic responsive layout and keyboard focus styles.
+
+## Install
+
+```bash
+npm install --save-dev jsdoc @mandolin/jsdoc-theme-hia
+```
+
+For HIA metadata support:
+
+```bash
+npm install --save-dev jsdoc @mandolin/jsdoc-plugin-hia-sys @mandolin/jsdoc-theme-hia
+```
+
+## Basic Usage
+
+Configure JSDoc to use the theme:
+
+```json
+{
+  "source": {
+    "include": ["src"]
+  },
+  "opts": {
+    "template": "node_modules/@mandolin/jsdoc-theme-hia",
+    "destination": "docs/api",
+    "recurse": true
+  }
+}
+```
+
+To consume HIA metadata, load the companion plugin as well:
+
+```json
+{
+  "plugins": ["node_modules/@mandolin/jsdoc-plugin-hia-sys/src/index.cjs"],
+  "source": {
+    "include": ["src"]
+  },
+  "opts": {
+    "template": "node_modules/@mandolin/jsdoc-theme-hia",
+    "destination": "docs/api",
+    "recurse": true,
+    "hia": {
+      "mode": "standalone",
+      "source": {
+        "link": {
+          "enabled": true,
+          "rootUrl": "https://github.com/example/project/blob/main"
+        },
+        "preview": {
+          "enabled": true,
+          "defaultExpanded": false
+        }
+      },
+      "i18n": {
+        "enabled": true,
+        "defaultLocale": "zh-CN",
+        "fallbackLocale": "en",
+        "locales": ["zh-CN", "en"],
+        "mode": "runtimeSwitch"
+      },
+      "theme": {
+        "skin": "classic",
+        "collapse": {
+          "docletsDefaultExpanded": true,
+          "sectionsDefaultExpanded": true,
+          "metadataDefaultExpanded": true
+        },
+        "languageControls": {
+          "mode": "auto",
+          "dropdownThreshold": 4
+        },
+        "code": {
+          "controls": true,
+          "fontFamily": "cascadia",
+          "fontSize": 12,
+          "lineHeight": 1.55,
+          "tabSize": 2,
+          "wrap": false
+        }
+      }
+    }
+  }
+}
+```
+
+## Generated Files
+
+The theme writes the following files to the configured destination:
+
+- `index.html`
+- `index.{locale}.html`, such as `index.zh-CN.html`
+- `hia-theme.css`
+- `hia-theme.js`
+- `search-index.json`
+- `i18n-index.json`
+- `hia-metadata.json`
+
+## Source Preview
+
+When used with `@mandolin/jsdoc-plugin-hia-sys`, definition source metadata is rendered in a `Source` section using relative paths. Explicit `@coderef` metadata is rendered separately in a `Source References` section. Both sections can display file links, line links, range hints and collapsible source previews.
+
+## Multilingual Rendering
+
+The theme supports two output styles from plugin metadata:
+
+- `runtimeSwitch`: `index.html` includes language controls and switches localized blocks in the browser.
+- `perLocale`: additional `index.{locale}.html` files are generated for individual locales.
+
+The theme consumes field-level translations for descriptions, params, returns, properties and examples when available. Missing translations fall back to the configured fallback locale or to the original JSDoc text.
+
+## UI Options
+
+Theme UI behavior can be configured under `opts.hia.theme`:
+
+- `skin`: built-in skin name, currently `classic`, `lumen` or `graphite`.
+- `collapse.docletsDefaultExpanded`: whether doclet cards are expanded by default.
+- `collapse.sectionsDefaultExpanded`: whether content sections are expanded by default.
+- `collapse.metadataDefaultExpanded`: whether metadata sections are expanded by default.
+- `languageControls.mode`: `auto`, `buttons` or `select`.
+- `languageControls.dropdownThreshold`: locale count at which `auto` switches from buttons to a select control.
+- `code.controls`: whether generated pages include runtime code display controls.
+- `code.fontFamily`: default source code font preset, currently `cascadia`, `consolas`, `mono` or `system`.
+- `code.fontSize`: default source code font size in pixels.
+- `code.lineHeight`: default source code line height.
+- `code.tabSize`: default source code tab size.
+- `code.wrap`: whether source code wraps by default.
+
+## Scripts
+
+```bash
+npm run check:syntax
+npm test
+npm run test:jsdoc
+npm run release:check
+npm run test:all
+```
+
+`npm test` checks renderer fixtures. `npm run test:jsdoc` builds the bundled example with real JSDoc. `npm run release:check` validates package metadata and required release files.
+
+## Compatibility
+
+- Node.js 18 or newer.
+- JSDoc 4.x.
+- CommonJS theme entry.
+
+## Stability
+
+Version `0.1.0` is an early public package. The theme is usable for small JSDoc projects and metadata experiments, but the rendering contract may evolve before a stable release.
+
+## License
+
+MIT

package/RELEASE_CHECKLIST.md

@@ -0,0 +1,43 @@
+# Release Checklist
+
+## Scope
+
+Package: `@mandolin/jsdoc-theme-hia`
+
+Version: `0.1.0`
+
+## Required Checks
+
+- [ ] `npm run check:syntax`
+- [ ] `npm test`
+- [ ] `npm run test:jsdoc`
+- [ ] `npm run clean:examples`
+- [ ] `npm run release:check`
+- [ ] `npm run test:all`
+- [ ] `npm pack --dry-run --json`
+
+## Manual Review
+
+- [ ] README describes standard JSDoc rendering, source preview and i18n.
+- [ ] `examples/basic/README.md` explains the example.
+- [ ] Desktop layout is usable.
+- [ ] Mobile layout is usable.
+- [ ] Keyboard focus is visible.
+- [ ] `THIRD_PARTY_NOTICES.md` is current.
+- [ ] `CHANGELOG.md` has the target version.
+- [ ] `package.json` keeps `publishConfig.access` as `public`.
+- [ ] Dry-run artifact contents are limited to theme sources, static assets, examples and release docs.
+- [ ] `examples/basic/out` is not present.
+- [ ] No `.tgz` dry-run tarball remains.
+
+## Publish Strategy
+
+- Keep version `0.1.0` for the first public package unless registry preflight shows it is already published.
+- Use `npm publish --access public` for the scoped package.
+- If publishing before W-P3.5 HIA Integration hardening, publish with `--tag next` and avoid promoting to `latest` until the integration producer contract is confirmed.
+
+## Current Boundaries
+
+- This is a single-page theme with per-locale HTML variants.
+- Search is local filtering, not a full search engine.
+- The theme is optimized for the JPHS metadata contract first.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,23 @@
+# Third Party Notices
+
+## Runtime Dependencies
+
+This theme has no bundled runtime dependency besides Node.js built-ins and browser APIs.
+
+## Peer Dependencies
+
+- `jsdoc` `^4.0.0` (`Apache-2.0`)
+
+`jsdoc` is expected to be installed by the consuming project or used through this package's development environment.
+
+## Development Dependencies
+
+- `jsdoc` `^4.0.5` (`Apache-2.0`)
+
+## Assets
+
+No third-party images, icon sets, fonts, copied Docdash code, or external CSS frameworks are bundled.
+
+## Legacy Material
+
+Older `docdash-hia` ideas were used as design reference only. This theme is a new implementation and does not copy source files from Docdash or the old repository.

package/examples/basic/README.md

@@ -0,0 +1,29 @@
+# Basic Example
+
+This example shows the core theme features:
+
+- JSDoc theme loading.
+- Standard JSDoc API rendering.
+- Source references from `jsdoc-plugin-hia-sys`.
+- Runtime language switching.
+- Per-locale HTML output.
+- Search data and local filtering.
+
+Run:
+
+```bash
+npm run test:jsdoc
+```
+
+Expected generated files under `examples/basic/out`:
+
+- `index.html`
+- `index.zh-CN.html`
+- `index.en.html`
+- `search-index.json`
+- `i18n-index.json`
+- `hia-metadata.json`
+- `hia-theme.css`
+- `hia-theme.js`
+
+Generated files are test artifacts and should not be committed.

package/examples/basic/jsdoc.conf.json

@@ -0,0 +1,52 @@
+{
+  "plugins": ["../jsdoc-plugin-hia-sys/src/index.cjs"],
+  "source": {
+    "include": ["examples/basic/src"]
+  },
+  "opts": {
+    "template": ".",
+    "destination": "examples/basic/out",
+    "recurse": true,
+    "hia": {
+      "mode": "standalone",
+      "source": {
+        "link": {
+          "enabled": true,
+          "rootUrl": "https://example.invalid/hia-docs",
+          "openMode": "new-tab"
+        },
+        "preview": {
+          "enabled": true,
+          "defaultExpanded": false
+        }
+      },
+      "i18n": {
+        "enabled": true,
+        "defaultLocale": "zh-CN",
+        "fallbackLocale": "en",
+        "locales": ["zh-CN", "en"],
+        "mode": "runtimeSwitch"
+      },
+      "theme": {
+        "skin": "classic",
+        "collapse": {
+          "docletsDefaultExpanded": true,
+          "sectionsDefaultExpanded": true,
+          "metadataDefaultExpanded": true
+        },
+        "languageControls": {
+          "mode": "auto",
+          "dropdownThreshold": 4
+        },
+        "code": {
+          "controls": true,
+          "fontFamily": "cascadia",
+          "fontSize": 12,
+          "lineHeight": 1.55,
+          "tabSize": 2,
+          "wrap": false
+        }
+      }
+    }
+  }
+}

package/examples/basic/src/demo.js

@@ -0,0 +1,65 @@
+"use strict";
+
+/**
+ * Theme demo module.
+ *
+ * @module theme
+ */
+
+/**
+ * Theme rendering options.
+ *
+ * @typedef {Object} ThemeOptions
+ * @property {string} [locale=en] Locale code.
+ * @property {boolean} [excited=false] Adds punctuation to the rendered text.
+ */
+
+/**
+ * Stateful theme renderer.
+ *
+ * @class
+ * @classdesc Wraps the demo rendering function for class rendering coverage.
+ * @param {ThemeOptions} [options] Default rendering options.
+ */
+class ThemeRenderer {
+  constructor(options = {}) {
+    this.options = options;
+  }
+
+  /**
+   * Render a message.
+   *
+   * @param {string} name Display name.
+   * @returns {string} Rendered message.
+   */
+  render(name) {
+    return themeDemo(name, this.options);
+  }
+}
+
+/**
+ * Theme demo function.
+ *
+ * @function themeDemo
+ * @param {string} name Display name.
+ * @param {ThemeOptions} [options] Rendering options.
+ * @returns {string} Demo text.
+ * @example <caption>Basic rendering</caption>
+ * // @coderef THEME_DEMO_BODY
+ * @coderef THEME_DEMO_BODY
+ * @hiaKey theme.demo
+ * @hiaText zh-CN 主题演示函数。
+ * @hiaText en Theme demo function.
+ */
+function themeDemo(name, options = {}) {
+  /* @codeblock THEME_DEMO_BODY */
+  const locale = options.locale || "en";
+  const message = locale === "zh-CN" ? `你好，${name}` : `Hello, ${name}`;
+  return options.excited ? `${message}!` : message;
+  /* @codeblockend THEME_DEMO_BODY */
+}
+
+module.exports = {
+  ThemeRenderer,
+  themeDemo
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@mandolin/jsdoc-theme-hia",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Independent HIA theme for JSDoc.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mandolin/jsdoc-theme-hia.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mandolin/jsdoc-theme-hia/issues"
+  },
+  "homepage": "https://github.com/mandolin/jsdoc-theme-hia#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "publish.js",
+  "files": [
+    "publish.js",
+    "src",
+    "static",
+    "examples/basic/jsdoc.conf.json",
+    "examples/basic/README.md",
+    "examples/basic/src",
+    "README.md",
+    "CHANGELOG.md",
+    "RELEASE_CHECKLIST.md",
+    "THIRD_PARTY_NOTICES.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check:syntax": "node --check publish.js && node --check src/metadata-reader.cjs && node --check src/render.cjs && node --check static/hia-theme.js && node --check test/render-fixture.cjs && node --check scripts/clean-generated.cjs && node --check scripts/release-check.cjs",
+    "clean:examples": "node scripts/clean-generated.cjs",
+    "release:check": "node scripts/release-check.cjs && npm pack --dry-run",
+    "test": "node test/render-fixture.cjs",
+    "test:jsdoc": "npx --yes jsdoc@4.0.5 -c examples/basic/jsdoc.conf.json",
+    "test:all": "npm run check:syntax && npm test && npm run test:jsdoc && npm run clean:examples && npm run release:check"
+  },
+  "keywords": [
+    "jsdoc",
+    "jsdoc-theme",
+    "theme",
+    "hia",
+    "documentation",
+    "source-preview",
+    "i18n"
+  ],
+  "peerDependencies": {
+    "jsdoc": "^4.0.0"
+  },
+  "devDependencies": {
+    "jsdoc": "^4.0.5"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/publish.js

@@ -0,0 +1,110 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const {
+  buildI18nPageData,
+  buildSearchIndex,
+  renderPage
+} = require("./src/render.cjs");
+const {
+  collectPageI18n,
+  summarizeHiaMetadata
+} = require("./src/metadata-reader.cjs");
+
+function getDoclets(data) {
+  if (typeof data !== "function") {
+    return [];
+  }
+
+  const seen = new Set();
+
+  return data()
+    .get()
+    .filter((doclet) => doclet.kind && doclet.kind !== "package" && !doclet.undocumented)
+    .filter((doclet) => {
+      const key = `${doclet.kind}:${doclet.longname || doclet.name || ""}`;
+
+      if (seen.has(key)) {
+        return false;
+      }
+
+      seen.add(key);
+      return true;
+    });
+}
+
+function writeFile(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), {
+    recursive: true
+  });
+  fs.writeFileSync(filePath, content, "utf8");
+}
+
+function copyStatic(destination) {
+  const css = fs.readFileSync(path.resolve(__dirname, "static/hia-theme.css"), "utf8");
+  const js = fs.readFileSync(path.resolve(__dirname, "static/hia-theme.js"), "utf8");
+
+  writeFile(path.join(destination, "hia-theme.css"), css);
+  writeFile(path.join(destination, "hia-theme.js"), js);
+}
+
+function getThemeOptions(opts) {
+  return opts && opts.hia && opts.hia.theme && typeof opts.hia.theme === "object"
+    ? opts.hia.theme
+    : {};
+}
+
+function publish(data, opts) {
+  const destination = path.resolve(opts.destination || "out");
+  const doclets = getDoclets(data);
+  const pageI18n = collectPageI18n(doclets);
+  const searchIndex = buildSearchIndex(doclets);
+  const theme = getThemeOptions(opts);
+  const page = renderPage({
+    title: "HIA JSDoc",
+    doclets,
+    theme
+  });
+
+  fs.mkdirSync(destination, {
+    recursive: true
+  });
+
+  copyStatic(destination);
+  writeFile(path.join(destination, "index.html"), page);
+  if (pageI18n.enabled) {
+    for (const locale of pageI18n.locales) {
+      writeFile(
+        path.join(destination, `index.${locale}.html`),
+        renderPage({
+          title: "HIA JSDoc",
+          doclets,
+          locale,
+          theme
+        })
+      );
+    }
+
+    writeFile(
+      path.join(destination, "i18n-index.json"),
+      JSON.stringify(buildI18nPageData(pageI18n), null, 2)
+    );
+  }
+  writeFile(path.join(destination, "search-index.json"), JSON.stringify(searchIndex, null, 2));
+  writeFile(
+    path.join(destination, "hia-metadata.json"),
+    JSON.stringify(
+      doclets.map((doclet) => ({
+        name: doclet.name || "",
+        longname: doclet.longname || "",
+        kind: doclet.kind || "",
+        hia: summarizeHiaMetadata(doclet)
+      })),
+      null,
+      2
+    )
+  );
+}
+
+exports.publish = publish;