@riebeckite/plugin-navigation 0.0.19 → 0.0.20

package/README.md

@@ -3,8 +3,8 @@
 Site navigation as a Riebeckite plugin. `navigation()` derives the primary
 navigation from the notes already in the vault, so an existing Obsidian vault
 becomes navigable with no Riebeckite-specific file and no required frontmatter.
-The plugin owns the navigation *model*; the Site shell owns rendering and
-placement.
+The plugin owns the navigation *model* and the *rendering mechanics*; the Site
+owns placement — where each rendered list appears.
 
 [日本語](./README_ja.md)
 
@@ -52,6 +52,34 @@ const secondary = model?.secondary ?? [];
 `resolveSiteNavigation` returns `null` when the plugin is not registered, so a
 site without navigation keeps working.
 
+### Rendering
+
+`SiteNav` renders a resolved tree as a `<nav>` landmark with nested lists. It
+owns the rendering mechanics — recursive children, active-path detection,
+locale-aware normalization, external-link handling, and `aria-current` — and
+ships the structural CSS for that `rb-nav` tree in its own `style.css`, loaded
+through the generated plugin styles. The Site decides where the tree is placed
+and whether to wrap it in a `<details>` element on small screens:
+
+```tsx
+import { SiteNav } from "@riebeckite/plugin-navigation";
+
+<header class="site-header rb-site-header">
+  <a href="/" class="site-header__home rb-site-header__home">My Site</a>
+  <SiteNav
+    items={primary}
+    path={c.req.path}
+    language={c.get("htmlLanguage")}
+  />
+</header>;
+```
+
+`path` is the current request path. `language` is the current content language;
+when set, `SiteNav` strips a matching `/language` prefix before resolving the
+active item, so unlocalized authored hrefs still match localized pages. Pass
+`localizeHref` to rewrite hrefs for the current language, `label` to change the
+landmark label, and `class`/`className` to extend the `<nav>` classes.
+
 ## Authored navigation
 
 Automated derivation cannot express everything, and some sites curate their
@@ -109,8 +137,9 @@ tab.
 - `resolveSiteNavigation(config, manifest)` — find the enabled plugin and build
   the model, or `null`
 - `validateNavigationOptions(options)` — option validation
+- `SiteNav` — render a resolved tree with the standard `rb-nav` structure
 - Types: `NavigationItem`, `NavigationOptions`, `NavigationSource`,
-  `SiteNavigation`
+  `SiteNavigation`, `SiteNavProps`
 
 ## Limitations
 
@@ -123,5 +152,5 @@ tab.
 
 ## See also
 
-- [Configuration reference](../../../docs/docs/reference/configuration.en.md)
-- [Plugin guide](../../../docs/docs/reference/plugin-api.en.md)
+- [Configuration reference](../../../docs/docs/reference/configuration.md)
+- [Plugin guide](../../../docs/docs/reference/plugin-api.md)

package/README_ja.md

@@ -3,8 +3,8 @@
 サイトナビゲーションを提供する Riebeckite プラグインです。`navigation()` は
 Vault にすでにあるノートから主要ナビゲーションを導出します。Riebeckite 専用の
 ファイルも必須 frontmatter も不要なので、既存の Obsidian Vault をそのまま
-公開できます。ナビゲーションの「モデル」はプラグインが持ち、描画と配置は
-Site シェルが担当します。
+公開できます。ナビゲーションの「モデル」と描画の仕組みはプラグインが持ち、
+配置は Site が担当します。
 
 [English](./README.md)
 
@@ -52,6 +52,35 @@ const secondary = model?.secondary ?? [];
 プラグインが登録されていない場合、`resolveSiteNavigation` は `null` を返すため、
 ナビゲーションのないサイトもそのまま動作します。
 
+### 描画
+
+`SiteNav` は解決済みのツリーを `<nav>` ランドマークとネストしたリストとして
+描画します。子の再帰描画、現在パスの判定、言語を考慮した正規化、外部リンクの
+扱い、`aria-current` といった描画の仕組みを担当し、その `rb-nav` ツリーを
+成立させる構造 CSS を自身の `style.css` に同梱します（自動生成される plugin
+styles 経由で読み込まれます）。ツリーをどこに置くか、モバイルで `<details>` を
+使うかは Site が決めます。
+
+```tsx
+import { SiteNav } from "@riebeckite/plugin-navigation";
+
+<header class="site-header rb-site-header">
+  <a href="/" class="site-header__home rb-site-header__home">My Site</a>
+  <SiteNav
+    items={primary}
+    path={c.req.path}
+    language={c.get("htmlLanguage")}
+  />
+</header>;
+```
+
+`path` は現在のリクエストパスです。`language` は現在のコンテンツ言語で、指定すると
+`SiteNav` は `/language` プレフィックスを取り除いてから現在のアイテムを判定します。
+そのため、言語プレフィックスのない手書き href でもローカライズされたページに
+一致します。`localizeHref` を渡すと現在の言語に合わせて href を書き換えられます。
+`label` でランドマークのラベルを、`class` / `className` で `<nav>` のクラスを
+拡張できます。
+
 ## 手書きナビゲーション
 
 自動導出ですべてを表現できるわけではなく、リンクを意図的に整えたいサイトも
@@ -109,8 +138,9 @@ navigation({
 - `resolveSiteNavigation(config, manifest)` — 有効なプラグインを見つけてモデルを
   構築する。なければ `null`
 - `validateNavigationOptions(options)` — オプションの検証
+- `SiteNav` — 解決済みツリーを標準の `rb-nav` 構造で描画する
 - 型: `NavigationItem`, `NavigationOptions`, `NavigationSource`,
-  `SiteNavigation`
+  `SiteNavigation`, `SiteNavProps`
 
 ## 制約
 
@@ -123,5 +153,5 @@ navigation({
 
 ## 関連リンク
 
-- [設定リファレンス](../../../docs/docs/reference/configuration.md)
-- [プラグイン API](../../../docs/docs/reference/plugin-api.md)
+- [設定リファレンス](../../../docs/docs/reference/configuration.ja.md)
+- [プラグイン API](../../../docs/docs/reference/plugin-api.ja.md)

package/dist/components/site-nav.d.ts

@@ -0,0 +1,28 @@
+import type { NavigationItem } from "../src/types.js";
+export type SiteNavProps = {
+    /** Navigation tree to render, in order. */
+    readonly items: readonly NavigationItem[];
+    /** Current request path, used to mark the active item. */
+    readonly path: string;
+    /**
+     * Current content language. When set, a matching `/language` prefix is
+     * stripped from `path` before the active item is resolved.
+     */
+    readonly language?: string;
+    /** Accessible label for the `<nav>` landmark. Defaults to "Site navigation". */
+    readonly label?: string;
+    /** Rewrites each internal href before it is rendered. */
+    readonly localizeHref?: (href: string) => string;
+    /** Extra classes appended to the `<nav>` landmark. */
+    readonly class?: string;
+    readonly className?: string;
+};
+/**
+ * Renders a resolved navigation tree as a `<nav>` landmark with nested lists.
+ *
+ * Owns the navigation rendering mechanics: recursive list markup, active-path
+ * semantics with locale-aware normalization, external-link handling, and the
+ * `aria-current` accessibility contract. The Site owns placement and decides
+ * where each tree is rendered.
+ */
+export declare function SiteNav(props: SiteNavProps): import("hono/jsx/jsx-dev-runtime").JSX.Element;

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import type { NavigationOptions } from "./src/types.js";
+export type { SiteNavProps } from "./components/site-nav.js";
+export { SiteNav } from "./components/site-nav.js";
 export { buildNavigation, NAVIGATION_PLUGIN_NAME, resolveSiteNavigation, } from "./src/navigation.js";
 export type { NavigationItem, NavigationOptions, NavigationSource, SiteNavigation, } from "./src/types.js";
 export declare function navigation(options?: NavigationOptions): import("@riebeckite/core").RiebeckitePlugin<NavigationOptions>;

package/dist/index.js

@@ -1,5 +1,5 @@
 // index.ts
-import { definePlugin } from "@riebeckite/core";
+import { createStyleAsset, definePlugin } from "@riebeckite/core";
 
 // src/navigation.ts
 import {
@@ -158,11 +158,92 @@ function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+// components/site-nav.tsx
+import { jsx, jsxs } from "hono/jsx/jsx-runtime";
+function SiteNav(props) {
+  return /* @__PURE__ */ jsx(
+    "nav",
+    {
+      class: joinClassNames("rb-nav", props.class, props.className),
+      "aria-label": props.label ?? "Site navigation",
+      children: /* @__PURE__ */ jsx(
+        NavigationItems,
+        {
+          items: props.items,
+          path: props.path,
+          language: props.language,
+          localizeHref: props.localizeHref
+        }
+      )
+    }
+  );
+}
+function NavigationItems(props) {
+  return /* @__PURE__ */ jsx("ul", { class: props.nested ? "rb-nav__list rb-nav__children" : "rb-nav__list", children: props.items.map((item) => /* @__PURE__ */ jsx(
+    NavigationItemView,
+    {
+      item,
+      path: props.path,
+      language: props.language,
+      localizeHref: props.localizeHref
+    }
+  )) });
+}
+function NavigationItemView(props) {
+  const { item, path, language, localizeHref } = props;
+  const active = item.href ? isActive(item.href, path, language) : false;
+  const href = item.href ? localizeHref?.(item.href) ?? item.href : void 0;
+  return /* @__PURE__ */ jsxs("li", { class: "rb-nav__item", children: [
+    href ? /* @__PURE__ */ jsx(
+      "a",
+      {
+        href,
+        class: active ? "rb-nav__link rb-nav__link--active" : "rb-nav__link",
+        "aria-current": active ? "page" : void 0,
+        target: item.external ? "_blank" : void 0,
+        rel: item.external ? "noreferrer" : void 0,
+        children: item.label
+      }
+    ) : /* @__PURE__ */ jsx("span", { class: "rb-nav__label", children: item.label }),
+    item.children && item.children.length > 0 ? /* @__PURE__ */ jsx(
+      NavigationItems,
+      {
+        items: item.children,
+        path,
+        language,
+        localizeHref,
+        nested: true
+      }
+    ) : null
+  ] });
+}
+function isActive(href, path, language) {
+  if (!href.startsWith("/")) return false;
+  const target = normalizePath(href);
+  const current = normalizePath(stripLanguagePrefix(path, language));
+  if (target === "/") return current === target;
+  return current === target || current.startsWith(`${target}/`);
+}
+function normalizePath(path) {
+  return path.replace(/\/+$/, "") || "/";
+}
+function stripLanguagePrefix(path, language) {
+  if (!language) return path;
+  if (path === `/${language}`) return "/";
+  const prefix = `/${language}/`;
+  if (path.startsWith(prefix)) return path.slice(language.length + 1);
+  return path;
+}
+function joinClassNames(...classNames) {
+  return classNames.filter(Boolean).join(" ");
+}
+
 // index.ts
 function navigation(options = {}) {
   return definePlugin({
     name: NAVIGATION_PLUGIN_NAME,
     options,
+    assets: [createStyleAsset("navigation")],
     validateOptions: validateNavigationOptions,
     outputDependencies: [{ type: "global" }]
   });
@@ -170,6 +251,7 @@ function navigation(options = {}) {
 var navigationPlugin = navigation;
 export {
   NAVIGATION_PLUGIN_NAME,
+  SiteNav,
   buildNavigation,
   navigation,
   navigationPlugin,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riebeckite/plugin-navigation",
-  "version": "0.0.19",
+  "version": "0.0.20",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",
@@ -11,14 +11,16 @@
       "import": "./dist/index.js",
       "source": "./index.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./style.css": "./style.css"
   },
   "dependencies": {
-    "@riebeckite/core": "0.0.19"
+    "hono": "^4.12.25",
+    "@riebeckite/core": "0.0.20"
   },
   "devDependencies": {
     "tsx": "^4.22.4",
-    "@riebeckite/test": "0.0.19"
+    "@riebeckite/test": "0.0.20"
   },
   "publishConfig": {
     "access": "public"
@@ -27,7 +29,8 @@
     "LICENSE",
     "README.md",
     "README_ja.md",
-    "dist"
+    "dist",
+    "style.css"
   ],
   "repository": {
     "type": "git",
@@ -47,7 +50,9 @@
   "engines": {
     "node": "^20.19.0 || >=22.12.0"
   },
-  "sideEffects": false,
+  "sideEffects": [
+    "./style.css"
+  ],
   "scripts": {
     "build": "node ../../../scripts/build_package.mjs",
     "test": "node --import tsx --test \"test/*.test.ts\""

package/style.css

@@ -0,0 +1,29 @@
+@layer components {
+  .rb-nav > .rb-nav__list,
+  .rb-nav__children {
+    margin: 0;
+    list-style: none;
+  }
+
+  .rb-nav > .rb-nav__list {
+    padding: 0;
+  }
+
+  .rb-nav__item {
+    position: relative;
+  }
+
+  .rb-nav__children {
+    display: none;
+    position: absolute;
+    top: 100%;
+    left: 0;
+    min-width: max-content;
+  }
+
+  .rb-nav__item:hover > .rb-nav__children,
+  .rb-nav__item:focus-within > .rb-nav__children {
+    display: flex;
+    flex-direction: column;
+  }
+}