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

- 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)
2025-12-11 13:11:56 +00:00
5 changed files with 119 additions and 30 deletions
--- a/README.md
+++ b/README.md
@@ -1,36 +1,36 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+Spectrum Next Explorer

-## Getting Started
+A Next.js application for exploring the Spectrum Next hardware. It includes a Register Explorer with real‑time search and deep‑linkable queries.

-First, run the development server:
+Features
+- Register Explorer parsed from `data/nextreg.txt`
+- Real‑time filtering with query‑string deep links (e.g. `/registers?q=vram`)
+- Bootstrap 5 theme with light/dark support

-```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
-```
+Quick start
+- Prerequisites: Node.js 20+, pnpm (recommended)
+- Install dependencies:
+  - `pnpm install`
+- Run in development (Turbopack, port 4000):
+  - `pnpm dev` then open http://localhost:4000
+- Build and start (production):
+  - `pnpm build`
+  - `pnpm start` (defaults to http://localhost:3000)
+- Lint:
+  - `pnpm lint`

-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+Project scripts (package.json)
+- `dev`: `PORT=4000 next dev --turbopack`
+- `build`: `next build --turbopack`
+- `start`: `next start`
+- `deploy-test`: push to `test.explorer.specnext.dev`
+- `deploy-prod`: push to `explorer.specnext.dev`

-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+Documentation
+- Docs index: `docs/index.md`
+- Getting Started: `docs/getting-started.md`
+- Architecture: `docs/architecture.md`
+- Register Explorer: `docs/registers.md`

-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
-
-## Learn More
-
-To learn more about Next.js, take a look at the following resources:
-
- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
-
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
-
-## Deploy on Vercel
-
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
-
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+License
+- See `LICENSE.txt` for details.
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -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)
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -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.
--- a/docs/index.md
+++ b/docs/index.md
@@ -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.
--- a/docs/registers.md
+++ b/docs/registers.md
@@ -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.