remove useKeyboardNavigation, update test-site to the 'netfoundry theme sandbox

CONTRIBUTING.md

@@ -24,10 +24,10 @@ docusaurus-shared/
 │       │   └── legacy.css        # Comprehensive styling
 │       └── __tests__/
 │
-├── test-site/                # Local development test site
-│   ├── docusaurus.config.ts
-│   ├── docs/
-│   └── src/
+│   └── test-site/            # Local dev sandbox for the theme
+│       ├── docusaurus.config.ts
+│       ├── docs/             # See packages/test-site/README.md
+│       └── src/
 │
 ├── unified-doc/              # Unified documentation build system
 ├── docs-linter/              # Vale + markdownlint tooling

README.md

@@ -7,13 +7,16 @@ Shared documentation theme, components, and tooling for NetFoundry's Docusaurus-
 ```
 docusaurus-shared/
 ├── packages/
-│   └── docusaurus-theme/     # @netfoundry/docusaurus-theme npm package
-├── test-site/                # Local development/testing site
-├── unified-doc/              # Unified documentation build system
+│   ├── docusaurus-theme/     # @netfoundry/docusaurus-theme npm package
+│   └── test-site/            # Local dev sandbox for the theme
+├── unified-doc/              # Unified production documentation build
 ├── docs-linter/              # Vale + markdownlint tooling
 └── bootstrap.sh              # New site bootstrapper
 ```
 
+See [`packages/test-site/README.md`](./packages/test-site/README.md) for the
+test-site dev loop, docs organization, and debug recipes.
+
 ## Quick Start
 
 ### Using the Theme
@@ -66,17 +69,25 @@ See the [theme README](./packages/docusaurus-theme/README.md) for full documenta
 git clone https://github.com/netfoundry/docusaurus-shared.git
 cd docusaurus-shared
 yarn install
-
-# Start development server
-yarn dev
-
-# Run tests
-yarn test
-
-# Build
-yarn build
 ```
 
+All routine commands run from the repo root. No `cd` into subfolders required:
+
+| Command                  | What it does                                              |
+|--------------------------|-----------------------------------------------------------|
+| `yarn test-site`         | Start the test-site dev sandbox (alias: `yarn dev`)       |
+| `yarn test-site:build`   | Production build of the test-site (alias: `yarn build`)   |
+| `yarn theme:build`       | Build `@netfoundry/docusaurus-theme`                      |
+| `yarn theme:watch`       | Watch the theme for incremental rebuilds                  |
+| `yarn unified`           | Start the unified-doc dev server                          |
+| `yarn unified:build`     | Production build of unified-doc                           |
+| `yarn test`              | Run theme unit tests                                      |
+| `yarn reinstall`         | Wipe every node_modules + lockfile, install fresh         |
+
+See [packages/test-site/README.md](./packages/test-site/README.md) for the full
+dev-loop walkthrough, debug recipes, and what hot-reloads vs. what needs a
+rebuild.
+
 ## Local Development
 
 See [packages/LOCAL-DEV.md](./packages/LOCAL-DEV.md) for the full local development guide, including how to use the test-site, test with remote sites via `file:` protocol, and publish.

package.json

@@ -1,13 +1,27 @@
 {
   "private": true,
   "workspaces": [
-    "packages/*",
-    "test-site"
+    "packages/*"
   ],
   "scripts": {
     "test": "yarn workspace @netfoundry/docusaurus-theme test",
+
+    "theme:build": "yarn workspace @netfoundry/docusaurus-theme build",
+    "theme:watch": "yarn workspace @netfoundry/docusaurus-theme watch",
+    "theme:clean": "yarn workspace @netfoundry/docusaurus-theme clean",
+
+    "test-site": "yarn workspace test-site start",
+    "test-site:build": "yarn workspace test-site build",
+    "test-site:clear": "yarn workspace test-site clear",
+
+    "unified": "yarn --cwd unified-doc start",
+    "unified:build": "yarn --cwd unified-doc build",
+    "unified:clear": "yarn --cwd unified-doc clear",
+
     "dev": "yarn workspace test-site start",
-    "build": "yarn workspace test-site build"
+    "build": "yarn workspace test-site build",
+
+    "reinstall": "node scripts/reinstall.mjs"
   },
   "packageManager": "yarn@1.22.22"
 }

packages/LOCAL-DEV.md

@@ -56,34 +56,50 @@ server — no reinstall needed.
 
 ## Step 2: Develop with test-site
 
-Start the dev server:
+Start the dev server from the **repo root**:
 
 ```bash
-cd packages/test-site
-yarn start
+yarn test-site
 ```
 
+(See the top-level `README.md` or `packages/test-site/README.md` for the full
+list of root scripts -- `theme:build`, `theme:watch`, `unified`, `reinstall`,
+etc.)
+
 ### What needs a rebuild
 
-| What you changed | What to do |
-|---|---|
-| `src/` components (React/TS) | Nothing extra — `yarn watch` recompiles automatically |
-| `theme/` component overrides | Nothing extra — `yarn watch` recompiles automatically |
-| `css/` stylesheets | Nothing extra — `yarn watch` copies CSS automatically |
+| What you changed                          | What to do                                                                |
+|-------------------------------------------|---------------------------------------------------------------------------|
+| `css/*.css` (shared theme stylesheets)    | **Nothing.** Hot-reloads live. See "Why CSS hot-reloads" below.            |
+| `src/**/*.ts(x)` (React/TS)               | `yarn build` (or run `yarn watch` in a second terminal)                   |
+| `src/**/*.module.css` (component CSS)     | `yarn build` (or `yarn watch`) -- the JS that imports it lives in `dist/` |
+| `theme/**` (Docusaurus overrides)         | `yarn build` (or `yarn watch`)                                            |
+| `packages/test-site/docs/**.mdx`          | Nothing -- Docusaurus watches it.                                          |
+| `packages/test-site/src/custom/custom.css`| Nothing -- Docusaurus watches it.                                          |
+
+### Why CSS hot-reloads
+
+The theme's plugin entry (`src/index.ts`) calls
+`require.resolve('../../css/theme.css')`. At runtime that file is
+`dist/src/index.js`, so the path lands at the package's **source** `css/`
+folder, not a built copy. Edits to `css/vars.css`, `css/layout.css`, etc.
+propagate immediately.
+
+If you ever need to revert this behavior (e.g. for a hermetic prod build),
+change `'../../css/theme.css'` back to `'../css/theme.css'` and have
+`scripts/build-css.mjs` copy `css/` -> `dist/css/` again.
 
 ### Watching theme changes during development
 
-`yarn watch` runs `tsc --watch` and a CSS file watcher together. Run it in a second
-terminal:
+`yarn theme:watch` runs `tsc --watch` and a CSS file watcher together. Run it
+in a second terminal:
 
 ```bash
-# Terminal 1 — theme watcher (TS + CSS)
-cd packages/docusaurus-theme
-yarn watch
+# Terminal 1 -- theme watcher (TS + per-component CSS)
+yarn theme:watch
 
-# Terminal 2 — test site dev server
-cd packages/test-site
-yarn start
+# Terminal 2 -- test-site dev server
+yarn test-site
 ```
 
 On every save, changes compile in ~1 second and Docusaurus hot-reloads the result.

packages/docusaurus-theme/css/layout.css

@@ -11,6 +11,13 @@ html {
     scrollbar-gutter: stable;
 }
 
+/* Hide focus outlines for mouse users; keep them for keyboard navigation.
+   Paired with useKeyboardNavigation() which toggles .navigation-with-keyboard
+   on <body> based on Tab vs mousedown. */
+body:not(.navigation-with-keyboard) *:not(input):focus {
+    outline: none;
+}
+
 /* Right navbar order: icons → toggle → search */
 .navbar__items--right > div:has(button.clean-btn),
 .navbar__items--right > button.clean-btn              { order: 10; }
@@ -40,4 +47,24 @@ html {
     max-width: var(--ziti-max-width);
 }
 
+/* Soften the Details/accordion component.
+   details.alert specificity is needed to beat rules in legacy.css. */
+details.alert {
+    background: var(--ifm-background-surface-color);
+    border-radius: var(--ifm-global-radius);
+    padding: 0.5rem 0.75rem;
+}
+details summary {
+    font-weight: 600;
+    cursor: pointer;
+}
+
+/* Inline code inside links (e.g. TOC headings) should inherit the link color.
+   Background uses --ifm-color-emphasis-100 so it flips automatically per theme. */
+a code {
+    color: inherit;
+    background: var(--ifm-color-emphasis-100);
+    border: 1px solid var(--ifm-color-emphasis-200);
+}
+
 

packages/docusaurus-theme/css/legacy.css

@@ -2173,7 +2173,12 @@ p > img {
         border: var(--ziti-code-block-border-thickness) solid var(--ziti-code-block-border-color);
     }
     div {
-        background: var(--ziti-code-block-background-color);
+        /* background: var(--ziti-code-block-background-color);
+           Commented out: was painting EVERY div inside any .alert, which made
+           <details class="alert">'s collapsibleContent wrapper and other nested
+           divs pick up the alert background color (visible as a stray blue strip
+           around code blocks inside Details). Theme-code-block + pre code rules
+           below still color the actual code surface. */
     }
 }
 .theme-code-block {

packages/docusaurus-theme/css/vars.css

@@ -1,6 +1,8 @@
 :root {
     --ifm-navbar-height: 50px;
     --ifm-navbar-padding-vertical: 0;
+    --ifm-pre-padding: 0.5rem;
+    --ifm-table-cell-padding: 0.25rem;
     --nf-docs-max-width: 1400px;
 
     --nf-icon-link-size: 1.5rem;

packages/docusaurus-theme/scripts/build-css.mjs

@@ -19,14 +19,11 @@ const walk = async (dir) => {
 
 await fs.mkdir("dist", { recursive: true });
 
-// copy css/ -> dist/css/
-try {
-  const files = await walk("css");
-  for (const f of files) {
-    if (!f.endsWith(".css")) continue;
-    await copyFile(f, path.join("dist", f));
-  }
-} catch {}
+// css/ is NOT copied to dist/css/. The theme's getClientModules() resolves
+// '../../css/theme.css' from dist/src/index.js, which lands at the package's
+// source css/ folder. This lets live edits to css/*.css flow into the dev
+// server without rebuilding. Published consumers still get css/ at the
+// package root via the `files` allowlist in package.json.
 
 // copy src/**/*.css -> dist/src/**/*
 try {

packages/docusaurus-theme/src/components/NetFoundryLayout/NetFoundryLayout.tsx

@@ -2,8 +2,7 @@ import React, {JSX} from "react";
 import clsx from "clsx";
 import ErrorBoundary from "@docusaurus/ErrorBoundary";
 import { ThemeClassNames } from "@docusaurus/theme-common";
-// @ts-ignore
-import { useKeyboardNavigation } from "@docusaurus/theme-common/internal";
+import { useKeyboardNavigation } from "../../hooks";
 import Head from "@docusaurus/Head";
 import useBaseUrl from "@docusaurus/useBaseUrl";
 

packages/docusaurus-theme/src/hooks/index.ts

@@ -0,0 +1 @@
+export * from './useKeyboardNavigation';

packages/docusaurus-theme/src/hooks/useKeyboardNavigation.ts

@@ -0,0 +1,31 @@
+import {useEffect} from 'react';
+
+export const keyboardFocusedClassName = 'navigation-with-keyboard';
+
+/**
+ * Adds `navigation-with-keyboard` to <body> on Tab, removes it on mousedown.
+ * Paired with the body:not(.navigation-with-keyboard) *:not(input):focus rule
+ * in layout.css so focus outlines only show for keyboard users.
+ *
+ * Local replacement for @docusaurus/theme-common/internal's useKeyboardNavigation,
+ * which lives under an /internal path that requires @ts-ignore.
+ */
+export function useKeyboardNavigation(): void {
+    useEffect(() => {
+        function handle(e: KeyboardEvent | MouseEvent) {
+            if (e.type === 'keydown' && (e as KeyboardEvent).key === 'Tab') {
+                document.body.classList.add(keyboardFocusedClassName);
+            }
+            if (e.type === 'mousedown') {
+                document.body.classList.remove(keyboardFocusedClassName);
+            }
+        }
+        document.addEventListener('keydown', handle);
+        document.addEventListener('mousedown', handle);
+        return () => {
+            document.body.classList.remove(keyboardFocusedClassName);
+            document.removeEventListener('keydown', handle);
+            document.removeEventListener('mousedown', handle);
+        };
+    }, []);
+}

packages/docusaurus-theme/src/index.ts

@@ -27,7 +27,15 @@ export default function themeNetFoundry(
         // consuming sites are expected to register. Adding it here would
         // double-load it on sites with Algolia and load it unnecessarily
         // on sites without search.
-        require.resolve('../css/theme.css'),
+        //
+        // Path note: at runtime this file is dist/src/index.js. We resolve
+        // up two levels to the package's *source* `css/` folder rather than
+        // a copy under `dist/css/`. That way live edits to css/*.css are
+        // picked up by the test-site dev server without needing to rerun
+        // `yarn build:css`. Published consumers also have `css/` at the
+        // package root (per the `files` allowlist), so this path is valid
+        // in both dev and prod.
+        require.resolve('../../css/theme.css'),
       ];
 
       // Add custom CSS if specified in options

packages/docusaurus-theme/src/ui.ts

@@ -5,3 +5,4 @@
  */
 export * from './components';
 export * from './docusaurus-envhelper';
+export * from './hooks';