NextBestNetwork/explorer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(registers): deep‑linkable search via ?q=; docs: add docs/ and update README

Browse Source 
- Register Explorer:
  - Sync search input with URL query param `q` for shareable deep links
  - Initialize search from `q` on load; update URL on input; remove `q` when cleared
  - Implemented with Next.js `useSearchParams`, `useRouter`, `usePathname`
  - File: src/app/registers/RegisterBrowser.tsx

- Documentation:
  - Add docs/ hub and initial guides
    - docs/index.md (docs index)
    - docs/getting-started.md (install/dev/build/start/lint/deploy)
    - docs/architecture.md (structure, theming, styling, key paths, scripts)
    - docs/registers.md (Register Explorer overview, search, deep links, implementation notes)
  - Rewrite README.md with project overview, features, quick start, scripts, and links to docs

Notes:
- Dev server uses port 4000 (Turbopack) via package.json
- Example deep link: /registers?q=vram

Date: 2025-12-11 13:11 (Junie@lucy.xalior.com)
This commit is contained in:
D. Rimron-Soutter
2025-12-11 13:11:56 +00:00
parent ea90d72252
commit 417fd997a7
5 changed files with 119 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
docs/architecture.md Normal file
View File

@@ -0,0 +1,30 @@
Architecture
Overview
- Framework: Next.js App Router (React 19)
- Styling: Bootstrap 5 with React-Bootstrap components and project SASS overrides
- Theming: Light/Dark theme set via data-bs-theme on <html>, initialized from a cookie or system preference in `src/app/layout.tsx`
Key paths
- App entry/layout: `src/app/layout.tsx`
- Global styles: `src/scss/nbn.scss` (imports Bootstrap, a Bootswatch-like layer, and project styles)
- Navbar: `src/components/Navbar.tsx`
- Register Explorer: `src/app/registers/*`
- Register parsing utilities: `src/utils/register_parser.ts` and `src/utils/register_parsers/*`
- Data: `data/nextreg.txt`
Styling & SASS
- `src/scss/nbn.scss` imports Bootstrap and local overrides in this order:
1. `variables` (custom Bootstrap variables)
2. Bootstrap core
3. `bootswatch` (theme tweaks)
4. `explorer` (project-specific styles)
Theming bootstrap
- On the server, `layout.tsx` reads the `NBN-theme` cookie (light/dark) and sets `data-bs-theme` on the HTML element.
- On the client, an inline script in the head ensures no flash of incorrect theme by immediately setting the attribute based on cookie or user preference.
Development scripts
- Dev: `pnpm dev` (port 4000 with Turbopack)
- Build: `pnpm build`
- Start: `pnpm start` (defaults to port 3000)

30
docs/getting-started.md Normal file
View File

@@ -0,0 +1,30 @@
Getting Started
This project is a Next.js app for exploring the Spectrum Next hardware. It uses the App Router, Bootstrap 5, and React-Bootstrap.
Prerequisites
- Node.js 20 or newer
- pnpm (recommended) or npm/yarn
Install
- pnpm install
- or: npm install
Run in development
- The dev server runs on port 4000 using Turbopack
- Command: pnpm dev
- Then open: http://localhost:4000
Build and start (production)
- Build: pnpm build
- Start: pnpm start
- Default start port: http://localhost:3000
Lint
- pnpm lint
Deployment shortcuts
- Two scripts are available in package.json:
- pnpm deploy-test: push the current branch to test.explorer.specnext.dev
- pnpm deploy-prod: push the current branch to explorer.specnext.dev
Ensure the corresponding Git remotes are configured locally before using these.

9
docs/index.md Normal file
View File

@@ -0,0 +1,9 @@
# Spectrum Next Explorer — Documentation
Welcome to the Spectrum Next Explorer docs. This site provides an overview of the project, how to develop and contribute, and details about key features like the Register Explorer and its search/deep‑linking capability.
- Getting Started: ./getting-started.md
- Architecture: ./architecture.md
- Register Explorer: ./registers.md
If you’re browsing on GitHub, the main README also links to these documents.

20
docs/registers.md Normal file
View File

@@ -0,0 +1,20 @@
Register Explorer
Overview
The Register Explorer lets you browse and search Spectrum Next registers parsed from `data/nextreg.txt`. Each register page shows address, access details, bit tables, and notes.
Searching
- Use the search input to filter registers in real time.
- The query is case‑insensitive and matches a combined `search` field per register (name, address, and keywords).
Deep links (query string)
- The search box syncs with the `q` query parameter so searches are shareable.
- Example: `/registers?q=vram`
- When you open this URL, the search box is pre‑filled with `vram` and the list is filtered immediately.
- Clearing the search removes `q` from the URL.
Implementation notes
- Component: `src/app/registers/RegisterBrowser.tsx`
- Uses Next.js navigation hooks: `useSearchParams`, `useRouter`, `usePathname`.
- On mount and when the URL changes, the component reads `q` and updates local state.
- On input change, the component updates state and calls `router.replace()` to keep the URL in sync without scrolling.