Spaces:

aymie-oh
/

codebookly

Sleeping

App Files Files Community

aymie-oh commited on 21 days ago

Commit

55d0d9e

1 Parent(s): ecee171

initial commit

Browse files

This view is limited to 50 files because it contains too many changes. See raw diff

Files changed (50) hide show

.gitignore +6 -0
codebookly/.gitignore +24 -0
codebookly/README.md +73 -0
codebookly/eslint.config.js +23 -0
codebookly/index.html +12 -0
codebookly/package-lock.json +0 -0
codebookly/package.json +34 -0
codebookly/public/codebookly-icon.svg +1 -0
codebookly/public/icons.svg +24 -0
codebookly/src/App.css +112 -0
codebookly/src/App.tsx +79 -0
codebookly/src/assets/codebookly-icon.webp +0 -0
codebookly/src/assets/codebookly.jpg +0 -0
codebookly/src/assets/hero.png +0 -0
codebookly/src/assets/react.svg +1 -0
codebookly/src/assets/vite.svg +1 -0
codebookly/src/branding.ts +6 -0
codebookly/src/features/codes/components/CodeCard.tsx +89 -0
codebookly/src/features/codes/components/CodeFullContextModal.tsx +75 -0
codebookly/src/features/codes/components/CodeListSection.tsx +124 -0
codebookly/src/features/codes/components/EnrichedCodeContent.tsx +107 -0
codebookly/src/features/codes/components/SelectionActionBar.tsx +75 -0
codebookly/src/features/codes/hooks/useCodeListSelection.ts +77 -0
codebookly/src/features/codes/hooks/useEnrichedCode.ts +57 -0
codebookly/src/features/codes/utils/exportCodesJson.ts +19 -0
codebookly/src/features/codes/utils/exportEnrichedJson.ts +31 -0
codebookly/src/features/codes/utils/fetchEnrichedForExport.ts +49 -0
codebookly/src/features/codes/utils/singleCodeToEnriched.ts +18 -0
codebookly/src/features/definitions/components/DefinitionRow.tsx +34 -0
codebookly/src/features/definitions/components/DefinitionsExplorer.tsx +57 -0
codebookly/src/features/definitions/components/DefinitionsSearchForm.tsx +77 -0
codebookly/src/features/definitions/components/DefinitionsTableSection.tsx +102 -0
codebookly/src/features/definitions/hooks/useDefinitionsBrowse.ts +102 -0
codebookly/src/features/definitions/services/definitionsBrowse.ts +18 -0
codebookly/src/features/layout/SectionChapterBanner.tsx +33 -0
codebookly/src/features/layout/SideBar.tsx +246 -0
codebookly/src/features/layout/SidebarAccordion.tsx +63 -0
codebookly/src/features/layout/sidebarTokens.ts +9 -0
codebookly/src/hooks/useCodebookApp.ts +249 -0
codebookly/src/index.css +34 -0
codebookly/src/main.tsx +22 -0
codebookly/src/services/apiClient.ts +7 -0
codebookly/src/services/apiService.ts +10 -0
codebookly/src/services/codeApi.ts +74 -0
codebookly/src/services/definitionsApi.ts +40 -0
codebookly/src/types/code.d.ts +0 -0
codebookly/src/types/codebook.ts +75 -0
codebookly/src/types/constants.ts +7 -0
codebookly/src/types/definitions.ts +14 -0
codebookly/src/types/navbar.ts +27 -0

.gitignore ADDED Viewed

	@@ -0,0 +1,6 @@

+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.env
+frontend/node_modules/

codebookly/.gitignore ADDED Viewed

	@@ -0,0 +1,24 @@

+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+node_modules
+dist
+dist-ssr
+*.local
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

codebookly/README.md ADDED Viewed

	@@ -0,0 +1,73 @@

+# React + TypeScript + Vite
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+Currently, two official plugins are available:
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
+## React Compiler
+The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+## Expanding the ESLint configuration
+If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+```js
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+      // Remove tseslint.configs.recommended and replace with this
+      tseslint.configs.recommendedTypeChecked,
+      // Alternatively, use this for stricter rules
+      tseslint.configs.strictTypeChecked,
+      // Optionally, add this for stylistic rules
+      tseslint.configs.stylisticTypeChecked,
+      // Other configs...
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+```js
+// eslint.config.js
+import reactX from 'eslint-plugin-react-x'
+import reactDom from 'eslint-plugin-react-dom'
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+      // Enable lint rules for React
+      reactX.configs['recommended-typescript'],
+      // Enable lint rules for React DOM
+      reactDom.configs.recommended,
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```

codebookly/eslint.config.js ADDED Viewed

	@@ -0,0 +1,23 @@

+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  },
+])

codebookly/index.html ADDED Viewed

	@@ -0,0 +1,12 @@

+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>codebookly</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

codebookly/package-lock.json ADDED Viewed

The diff for this file is too large to render. See raw diff

codebookly/package.json ADDED Viewed

	@@ -0,0 +1,34 @@

+{
+  "name": "codebookly",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@tailwindcss/vite": "^4.2.2",
+    "axios": "^1.14.0",
+    "lucide-react": "^1.7.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "tailwindcss": "^4.2.2"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@types/node": "^24.12.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "eslint": "^9.39.4",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.5.2",
+    "globals": "^17.4.0",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.57.0",
+    "vite": "^8.0.1"
+  }
+}

codebookly/public/codebookly-icon.svg ADDED Viewed

codebookly/public/icons.svg ADDED Viewed

codebookly/src/App.css ADDED Viewed

	@@ -0,0 +1,112 @@

+:root {
+  --primary: #3b82f6;
+  --text-main: #ececec;
+  --text-muted: #94a3b8;
+  --bg-card: #1e1e1e;
+  --border: #334155;
+}
+.code-card {
+  background: var(--bg-card);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  padding: 1.5rem;
+  margin-bottom: 1.25rem;
+}
+.code-card:hover {
+  border-color: var(--primary);
+}
+.section-path {
+  display: block;
+  font-size: 0.75rem;
+  text-transform: uppercase;
+  color: var(--primary);
+  letter-spacing: 0.05em;
+  margin-bottom: 0.25rem;
+}
+/* App.css */
+.main-content-wrapper {
+  width: 1126px;
+  max-width: 100%;
+  margin: auto;
+  text-align: center;
+  min-height: 100svh;
+  display: flex;
+  flex-direction: column;
+  box-sizing: border-box;
+  /* Ensure it has a background if the root background is different */
+  /* background-color: #0f172a; */
+}
+.code-number {
+  font-size: 1.25rem;
+  font-weight: 800;
+  margin: 0;
+  color: var(--text-main);
+}
+.code-title {
+  font-size: 1rem;
+  font-weight: 600;
+  color: var(--text-muted);
+  margin-top: 0.25rem;
+  margin-bottom: 1rem;
+}
+.code-content {
+  line-height: 1.6;
+  font-size: 0.95rem;
+  color: var(--text-main);
+  margin-bottom: 1.5rem;
+}
+.card-footer {
+  display: flex;
+  gap: 12px;
+  align-items: center;
+  border-top: 1px solid var(--border);
+  padding-top: 1rem;
+}
+.badge {
+  background: #334155;
+  padding: 2px 8px;
+  border-radius: 4px;
+  font-size: 0.7rem;
+  font-weight: bold;
+  text-transform: uppercase;
+}
+.metadata {
+  font-size: 0.8rem;
+  color: var(--text-muted);
+}
+/* Target the scrollable area in the Sidebar */
+nav.flex-1 {
+  /* Firefox */
+  scrollbar-width: thin;
+  scrollbar-color: var(--border) transparent;
+}
+/* Chrome, Edge, and Safari */
+nav.flex-1::-webkit-scrollbar {
+  width: 5px; /* Adjust this for thickness */
+}
+nav.flex-1::-webkit-scrollbar-track {
+  background: transparent; /* Keeps it clean */
+}
+nav.flex-1::-webkit-scrollbar-thumb {
+  background-color: var(--border); /* Matches your site borders */
+  border-radius: 20px; /* Makes it rounded */
+}
+nav.flex-1::-webkit-scrollbar-thumb:hover {
+  background-color: var(--accent); /* Optional: turns accent color on hover */
+}

codebookly/src/App.tsx ADDED Viewed

	@@ -0,0 +1,79 @@

+import "./App.css";
+// import { CODEBOOKLY_ICON_SRC } from "./branding";
+import { Library } from "lucide-react";
+import { CodeListSection } from "./features/codes/components/CodeListSection";
+import { DefinitionsExplorer } from "./features/definitions/components/DefinitionsExplorer";
+import { SectionChapterBanner } from "./features/layout/SectionChapterBanner";
+import SideBar from "./features/layout/SideBar";
+import { useCodebookApp } from "./hooks/useCodebookApp";
+function App() {
+  const {
+    mainView,
+    setMainView,
+    codes,
+    codesAreaLoading,
+    sectionChapterMeta,
+    designationMeta,
+    agencyMeta,
+    sections,
+    chapters,
+    designations,
+    agencies,
+    handleSectionSelect,
+    handleChapterSelect,
+    handleDesignationSelect,
+    handleAgencySelect,
+  } = useCodebookApp();
+  return (
+    <div className="flex min-h-screen bg-[var(--bg)]">
+      <SideBar
+        sections={sections}
+        chapters={chapters}
+        designations={designations}
+        agencies={agencies}
+        onSectionSelect={handleSectionSelect}
+        onChapterSelect={handleChapterSelect}
+        onDesignationSelect={handleDesignationSelect}
+        onAgencySelect={handleAgencySelect}
+        onDefinitionsSelect={() => setMainView("definitions")}
+        definitionsActive={mainView === "definitions"}
+      />
+      <div className="flex-1 ml-20 md:ml-72">
+        <main className="max-w-[1600px] mx-auto px-4 py-6 sm:px-6 md:px-10 md:py-10 lg:px-12 lg:py-12">
+          <header className="mb-12 flex flex-wrap items-center gap-4 md:gap-5">
+            <Library size={60} className="text-blue-500" />
+            <h1 className="text-3xl md:text-3xl font-black text-[var(--text-h)] m-0">
+              Codebookly Admin
+            </h1>
+          </header>
+          {mainView === "definitions" ? (
+            <DefinitionsExplorer />
+          ) : (
+            <>
+              {sectionChapterMeta ? (
+                <SectionChapterBanner meta={sectionChapterMeta} />
+              ) : null}
+              {designationMeta ? (
+                <SectionChapterBanner
+                  meta={designationMeta}
+                  contextLabel="Committee designation"
+                />
+              ) : null}
+              {agencyMeta ? (
+                <SectionChapterBanner meta={agencyMeta} contextLabel="Agency" />
+              ) : null}
+              <CodeListSection codes={codes} loading={codesAreaLoading} />
+            </>
+          )}
+        </main>
+      </div>
+    </div>
+  );
+}
+export default App;

codebookly/src/assets/codebookly-icon.webp ADDED Viewed

codebookly/src/assets/codebookly.jpg ADDED Viewed

codebookly/src/assets/hero.png ADDED Viewed

codebookly/src/assets/react.svg ADDED Viewed

codebookly/src/assets/vite.svg ADDED Viewed

codebookly/src/branding.ts ADDED Viewed

	@@ -0,0 +1,6 @@

+import codebooklyIconUrl from "./assets/codebookly-icon.webp";
+import codebookIconUrl from "./assets/codebookly.jpg";
+/** Resolved by Vite — use for `<img src>` and favicon (see `main.tsx`). */
+export const CODEBOOKLY_ICON_SRC = codebooklyIconUrl;
+export const CODEBOOK_ICON_SRC = codebookIconUrl;

codebookly/src/features/codes/components/CodeCard.tsx ADDED Viewed

	@@ -0,0 +1,89 @@

+import { memo } from "react";
+import type { CodeRecord } from "../../../types/codebook";
+type Props = {
+  code: CodeRecord;
+  index: number;
+  selected: boolean;
+  onSelectionClick: (
+    e: React.MouseEvent<HTMLInputElement>,
+    index: number,
+    id: string,
+  ) => void;
+  onOpenDetail: () => void;
+};
+function CodeCardImpl({
+  code,
+  index,
+  selected,
+  onSelectionClick,
+  onOpenDetail,
+}: Props) {
+  return (
+    <article
+      className={`rounded-md border bg-card ${
+        selected
+          ? "ring-2 ring-primary border-primary shadow-sm"
+          : "border-border-ui hover:border-primary"
+      }`}
+    >
+      <div className="flex gap-2 p-3">
+        <label
+          className="shrink-0 cursor-pointer pt-0.5 select-none"
+          onClick={(e) => e.stopPropagation()}
+          data-code-checkbox
+        >
+          <input
+            type="checkbox"
+            readOnly
+            className="size-3.5 rounded border-border-ui accent-[var(--primary)] cursor-pointer"
+            checked={selected}
+            onClick={(e) => onSelectionClick(e, index, code.code)}
+            aria-label={`Select code ${code.code}`}
+          />
+        </label>
+        <button
+          type="button"
+          onClick={onOpenDetail}
+          className="flex-1 min-w-0 text-left rounded-md focus:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg)] cursor-pointer border-0 bg-transparent p-0 font-inherit"
+        >
+          <div className="mb-2">
+            <span className="block text-[0.80rem] uppercase text-primary tracking-wide mb-0.5 font-medium line-clamp-1">
+              {code.section_code}
+              {code.section_title != null && code.section_title !== ""
+                ? ` — ${code.section_title}`
+                : ""}
+            </span>
+            <h2 className="text-sm font-extrabold m-0 text-text-main leading-tight">
+              {code.code}
+            </h2>
+            <h3 className="text-xs font-semibold text-text-muted mt-0.5 mb-0 line-clamp-2 leading-snug">
+              {code.title}
+            </h3>
+          </div>
+          <div className="mb-2">
+            <p className="leading-snug text-[0.8rem] text-text-main line-clamp-3 m-0">
+              {code.content}
+            </p>
+          </div>
+          <div className="flex flex-wrap gap-1.5 items-center pt-2 border-t border-border-ui">
+            <span className="bg-border-ui px-1.5 py-0.5 rounded text-[0.65rem] font-bold uppercase text-text-main">
+              Ch. {code.chapter}
+            </span>
+            {code.table && (
+              <span className="text-[0.7rem] text-text-muted truncate max-w-full">
+                Tbl {code.table}
+              </span>
+            )}
+          </div>
+        </button>
+      </div>
+    </article>
+  );
+}
+export default memo(CodeCardImpl);

codebookly/src/features/codes/components/CodeFullContextModal.tsx ADDED Viewed

	@@ -0,0 +1,75 @@

+import { useEnrichedCode } from "../hooks/useEnrichedCode";
+import { EnrichedCodeContent } from "./EnrichedCodeContent";
+type Props = {
+  open: boolean;
+  codeId: string | null;
+  onClose: () => void;
+};
+export function CodeFullContextModal({ open, codeId, onClose }: Props) {
+  const state = useEnrichedCode(open ? codeId : null);
+  if (!open) return null;
+  return (
+    <div
+      className="fixed inset-0 z-50 flex items-center justify-center p-4 md:p-8"
+      role="presentation"
+    >
+      <button
+        type="button"
+        aria-label="Close dialog"
+        className="absolute inset-0 bg-black/60 backdrop-blur-[2px] cursor-default border-0 p-0"
+        onClick={onClose}
+      />
+      <div
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="full-context-title"
+        className="relative z-10 w-full max-w-3xl max-h-[min(90vh,900px)] overflow-y-auto rounded-xl border border-border-ui bg-card p-6 md:p-8 shadow-xl text-left"
+      >
+        <div className="flex justify-between items-start gap-4 mb-6 sticky top-0 bg-card pb-2 border-b border-border-ui -mx-6 px-6 md:-mx-8 md:px-8 z-10">
+          <h2
+            id="full-context-title"
+            className="text-lg font-bold text-text-main m-0"
+          >
+            Full code context
+            {codeId != null ? (
+              <span className="text-text-muted font-normal"> · {codeId}</span>
+            ) : null}
+          </h2>
+          <button
+            type="button"
+            onClick={onClose}
+            className="shrink-0 rounded-lg px-3 py-1.5 text-sm font-semibold bg-border-ui text-text-main hover:opacity-90 border-0 cursor-pointer"
+          >
+            Close
+          </button>
+        </div>
+        {state.status === "idle" || state.status === "loading" ? (
+          <p className="text-text-muted m-0">Loading…</p>
+        ) : null}
+        {state.status === "error" ? (
+          <p className="text-red-400 m-0" role="alert">
+            {state.message}
+          </p>
+        ) : null}
+        {state.status === "ok" ? (
+          <div className="space-y-4">
+            {state.partial ? (
+              <p className="text-sm text-text-muted m-0 rounded-lg border border-border-ui bg-[var(--bg-card)] px-3 py-2">
+                Loaded code text only; standards, committee designations, and index
+                terms were not available.
+              </p>
+            ) : null}
+            <EnrichedCodeContent enriched={state.data} />
+          </div>
+        ) : null}
+      </div>
+    </div>
+  );
+}

codebookly/src/features/codes/components/CodeListSection.tsx ADDED Viewed

	@@ -0,0 +1,124 @@

+import { useCallback, useState } from "react";
+import { Loader2 } from "lucide-react";
+import type { CodeRecord } from "../../../types/codebook";
+import CodeCard from "./CodeCard";
+import { CodeFullContextModal } from "./CodeFullContextModal";
+import { SelectionActionBar } from "./SelectionActionBar";
+import { useCodeListSelection } from "../hooks/useCodeListSelection";
+import { downloadCodesJson } from "../utils/exportCodesJson";
+import { downloadEnrichedJson } from "../utils/exportEnrichedJson";
+import { fetchEnrichedForExport } from "../utils/fetchEnrichedForExport";
+type Props = {
+  codes: CodeRecord[];
+  /** True while initial shell fetch or a browse navigation (section/chapter/etc.) is in flight */
+  loading?: boolean;
+};
+export function CodeListSection({ codes, loading = false }: Props) {
+  const [detailCode, setDetailCode] = useState<string | null>(null);
+  const [enrichedDownloadBusy, setEnrichedDownloadBusy] = useState(false);
+  const {
+    selected,
+    selectedCount,
+    clear,
+    selectAllVisible,
+    handleCheckboxClick,
+    selectedRecords,
+  } = useCodeListSelection(codes);
+  const handleOpenDetail = useCallback((code: string) => {
+    setDetailCode(code);
+  }, []);
+  const handleCloseModal = useCallback(() => {
+    setDetailCode(null);
+  }, []);
+  const handleDownloadJson = useCallback(() => {
+    if (selectedRecords.length === 0) return;
+    const stamp = new Date().toISOString().slice(0, 10);
+    downloadCodesJson(selectedRecords, `codebookly-export-${stamp}.json`);
+  }, [selectedRecords]);
+  const handleDownloadEnrichedJson = useCallback(async () => {
+    if (selectedRecords.length === 0) return;
+    setEnrichedDownloadBusy(true);
+    try {
+      const ids = selectedRecords.map((c) => c.code);
+      const { enriched, errors } = await fetchEnrichedForExport(ids);
+      const stamp = new Date().toISOString().slice(0, 10);
+      downloadEnrichedJson(
+        enriched,
+        `codebookly-enriched-${stamp}.json`,
+        errors.length > 0 ? errors : undefined,
+      );
+    } finally {
+      setEnrichedDownloadBusy(false);
+    }
+  }, [selectedRecords]);
+  if (loading) {
+    return (
+      <div
+        className="flex min-h-[12rem] flex-col items-center justify-center gap-3 rounded-xl border border-border-ui bg-card px-6 py-16 text-text-muted"
+        role="status"
+        aria-live="polite"
+        aria-busy="true"
+      >
+        <Loader2 className="animate-spin text-primary" size={36} aria-hidden />
+        <p className="m-0 text-sm font-medium text-text-main">Loading codes…</p>
+      </div>
+    );
+  }
+  if (codes.length === 0) return null;
+  return (
+    <>
+      <div className={selectedCount > 0 ? "pb-28 md:pb-24" : undefined}>
+        <p className="text-sm text-text-muted m-0 mb-4 max-w-3xl">
+          Use checkboxes to select codes.{" "}
+          <span className="text-text-main">Ctrl/Cmd+click</span> toggles one
+          without clearing others.{" "}
+          <span className="text-text-main">Shift+click</span> selects a range
+          from the last checkbox you used.{" "}
+          <span className="text-text-main">Codes JSON</span> uses the list only;{" "}
+          <span className="text-text-main">Enriched JSON</span> loads chapter
+          info, standards, designations, and index terms per code (one request
+          each).
+        </p>
+        <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
+          {codes.map((code, index) => (
+            <CodeCard
+              key={code.code}
+              code={code}
+              index={index}
+              selected={selected.has(code.code)}
+              onSelectionClick={handleCheckboxClick}
+              onOpenDetail={() => handleOpenDetail(code.code)}
+            />
+          ))}
+        </div>
+      </div>
+      <CodeFullContextModal
+        open={detailCode !== null}
+        codeId={detailCode}
+        onClose={handleCloseModal}
+      />
+      <SelectionActionBar
+        count={selectedCount}
+        visibleCount={codes.length}
+        onClear={clear}
+        onSelectAllVisible={selectAllVisible}
+        onDownloadJson={handleDownloadJson}
+        onDownloadEnrichedJson={handleDownloadEnrichedJson}
+        enrichedDownloadBusy={enrichedDownloadBusy}
+      />
+    </>
+  );
+}

codebookly/src/features/codes/components/EnrichedCodeContent.tsx ADDED Viewed

	@@ -0,0 +1,107 @@

+import { memo } from "react";
+import type { EnrichedCode } from "../../../types/codebook";
+function EnrichedCodeContentImpl({ enriched }: { enriched: EnrichedCode }) {
+  const { code, standards, committee_designations, index_terms } = enriched;
+  return (
+    <div className="space-y-8 text-left">
+      <section>
+        <span className="block text-[0.75rem] uppercase text-primary tracking-wider mb-1 font-medium">
+          {code.section_code}
+          {code.section_title != null && code.section_title !== ""
+            ? ` — ${code.section_title}`
+            : ""}
+        </span>
+        <h2 className="text-xl font-extrabold m-0 text-text-main">{code.code}</h2>
+        <h3 className="text-base font-semibold text-text-muted mt-1 mb-4">
+          {code.title}
+        </h3>
+        <p className="leading-relaxed text-[0.95rem] text-text-main whitespace-pre-wrap">
+          {code.content}
+        </p>
+        <div className="flex flex-wrap gap-3 items-center pt-4 mt-4 border-t border-border-ui">
+          <span className="bg-border-ui px-2 py-0.5 rounded text-[0.7rem] font-bold uppercase text-text-main">
+            Chapter {code.chapter}
+          </span>
+          {code.table ? (
+            <span className="text-[0.8rem] text-text-muted">Table {code.table}</span>
+          ) : null}
+          {code.figure ? (
+            <span className="text-[0.8rem] text-text-muted">Figure {code.figure}</span>
+          ) : null}
+        </div>
+      </section>
+      {standards.length > 0 ? (
+        <section className="border-t border-border-ui pt-6">
+          <h4 className="text-sm font-bold uppercase tracking-wide text-primary mb-3">
+            Standards
+          </h4>
+          <ul className="list-none m-0 p-0 space-y-4">
+            {standards.map((s, i) => (
+              <li
+                key={`${s.agency}-${s.standard_id}-${i}`}
+                className="rounded-md border border-border-ui bg-[var(--bg-card)] p-3"
+              >
+                <div className="text-[0.8rem] font-bold text-text-main">
+                  {s.agency} · {s.standard_id}
+                </div>
+                {s.definition ? (
+                  <p className="text-[0.85rem] text-text-muted m-0 mt-2 leading-relaxed">
+                    {s.definition}
+                  </p>
+                ) : null}
+              </li>
+            ))}
+          </ul>
+        </section>
+      ) : null}
+      {committee_designations.length > 0 ? (
+        <section className="border-t border-border-ui pt-6">
+          <h4 className="text-sm font-bold uppercase tracking-wide text-primary mb-3">
+            Committee designations
+          </h4>
+          <ul className="list-none m-0 p-0 space-y-2">
+            {committee_designations.map((c) => (
+              <li key={c.letter_tag} className="text-[0.9rem]">
+                <span className="font-bold text-text-main">{c.letter_tag}</span>
+                {c.description ? (
+                  <span className="text-text-muted"> — {c.description}</span>
+                ) : null}
+              </li>
+            ))}
+          </ul>
+        </section>
+      ) : null}
+      {index_terms.length > 0 ? (
+        <section className="border-t border-border-ui pt-6">
+          <h4 className="text-sm font-bold uppercase tracking-wide text-primary mb-3">
+            Index terms
+          </h4>
+          <ul className="list-none m-0 p-0 space-y-3">
+            {index_terms.map((t) => (
+              <li
+                key={t.id}
+                className="text-[0.85rem] border-l-2 border-primary/40 pl-3"
+              >
+                <div className="font-semibold text-text-main">{t.term}</div>
+                {t.label ? (
+                  <div className="text-text-muted mt-0.5">{t.label}</div>
+                ) : null}
+                <div className="text-text-muted text-[0.8rem] mt-1">
+                  {t.ref_type} {t.ref_id}
+                  {t.breadcrumb ? ` · ${t.breadcrumb}` : ""}
+                </div>
+              </li>
+            ))}
+          </ul>
+        </section>
+      ) : null}
+    </div>
+  );
+}
+export const EnrichedCodeContent = memo(EnrichedCodeContentImpl);

codebookly/src/features/codes/components/SelectionActionBar.tsx ADDED Viewed

	@@ -0,0 +1,75 @@

+import { Download, Layers, Loader2 } from "lucide-react";
+type Props = {
+  count: number;
+  onClear: () => void;
+  onSelectAllVisible: () => void;
+  onDownloadJson: () => void;
+  onDownloadEnrichedJson: () => void;
+  enrichedDownloadBusy: boolean;
+  visibleCount: number;
+};
+export function SelectionActionBar({
+  count,
+  onClear,
+  onSelectAllVisible,
+  onDownloadJson,
+  onDownloadEnrichedJson,
+  enrichedDownloadBusy,
+  visibleCount,
+}: Props) {
+  if (count === 0) return null;
+  return (
+    <div
+      className="fixed bottom-0 right-0 z-40 border-t border-[var(--border)] bg-[var(--bg-card)]/95 backdrop-blur-sm px-4 py-3 shadow-lg left-20 md:left-72"
+      role="region"
+      aria-label="Selection actions"
+    >
+      <div className="max-w-[1600px] mx-auto flex flex-wrap items-center justify-between gap-3">
+        <p className="text-sm text-[var(--text-main)] m-0">
+          <span className="font-semibold tabular-nums">{count}</span> selected
+        </p>
+        <div className="flex flex-wrap items-center gap-2">
+          <button
+            type="button"
+            onClick={onSelectAllVisible}
+            disabled={visibleCount === 0}
+            className="text-sm font-medium rounded-lg px-3 py-2 border border-[var(--border)] text-[var(--text-main)] hover:bg-[#334155] disabled:opacity-40 disabled:pointer-events-none"
+          >
+            Select all visible
+          </button>
+          <button
+            type="button"
+            onClick={onClear}
+            className="text-sm font-medium rounded-lg px-3 py-2 border border-[var(--border)] text-[var(--text-muted)] hover:text-[var(--text-main)] hover:bg-[#334155]"
+          >
+            Clear
+          </button>
+          <button
+            type="button"
+            onClick={onDownloadJson}
+            className="inline-flex items-center gap-2 text-sm font-semibold rounded-lg px-4 py-2 bg-[var(--primary)] text-white hover:opacity-90"
+          >
+            <Download size={16} aria-hidden />
+            Codes JSON
+          </button>
+          <button
+            type="button"
+            onClick={onDownloadEnrichedJson}
+            disabled={enrichedDownloadBusy}
+            className="inline-flex items-center gap-2 text-sm font-semibold rounded-lg px-4 py-2 border border-[var(--primary)] text-[var(--primary)] hover:bg-[#334155]/50 disabled:opacity-50 disabled:pointer-events-none"
+          >
+            {enrichedDownloadBusy ? (
+              <Loader2 size={16} className="animate-spin" aria-hidden />
+            ) : (
+              <Layers size={16} aria-hidden />
+            )}
+            {enrichedDownloadBusy ? "Fetching…" : "Enriched JSON"}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

codebookly/src/features/codes/hooks/useCodeListSelection.ts ADDED Viewed

	@@ -0,0 +1,77 @@

+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type { CodeRecord } from "../../../types/codebook";
+export function useCodeListSelection(items: CodeRecord[]) {
+  const orderedIds = useMemo(() => items.map((c) => c.code), [items]);
+  const [selected, setSelected] = useState<Set<string>>(() => new Set());
+  const lastIndexRef = useRef<number | null>(null);
+  useEffect(() => {
+    setSelected(new Set());
+    lastIndexRef.current = null;
+  }, [items]);
+  const clear = useCallback(() => {
+    setSelected(new Set());
+    lastIndexRef.current = null;
+  }, []);
+  const selectAllVisible = useCallback(() => {
+    setSelected(new Set(orderedIds));
+    lastIndexRef.current = orderedIds.length > 0 ? orderedIds.length - 1 : null;
+  }, [orderedIds]);
+  const handleCheckboxClick = useCallback(
+    (e: React.MouseEvent<HTMLInputElement>, index: number, id: string) => {
+      e.preventDefault();
+      e.stopPropagation();
+      if (e.shiftKey && lastIndexRef.current !== null) {
+        const a = Math.min(lastIndexRef.current, index);
+        const b = Math.max(lastIndexRef.current, index);
+        const range = orderedIds.slice(a, b + 1);
+        setSelected((prev) => {
+          const next = new Set(prev);
+          for (const rid of range) next.add(rid);
+          return next;
+        });
+        lastIndexRef.current = index;
+        return;
+      }
+      if (e.metaKey || e.ctrlKey) {
+        setSelected((prev) => {
+          const next = new Set(prev);
+          if (next.has(id)) next.delete(id);
+          else next.add(id);
+          return next;
+        });
+        lastIndexRef.current = index;
+        return;
+      }
+      setSelected((prev) => {
+        const next = new Set(prev);
+        if (next.has(id)) next.delete(id);
+        else next.add(id);
+        return next;
+      });
+      lastIndexRef.current = index;
+    },
+    [orderedIds],
+  );
+  const selectedRecords = useMemo(
+    () => items.filter((row) => selected.has(row.code)),
+    [items, selected],
+  );
+  return {
+    selected,
+    selectedCount: selected.size,
+    clear,
+    selectAllVisible,
+    handleCheckboxClick,
+    selectedRecords,
+  };
+}

codebookly/src/features/codes/hooks/useEnrichedCode.ts ADDED Viewed

	@@ -0,0 +1,57 @@

+import { useEffect, useState } from "react";
+import { codeService } from "../../../services/codeApi";
+import type { EnrichedCode } from "../../../types/codebook";
+import { singleCodeResponseToEnriched } from "../utils/singleCodeToEnriched";
+export type EnrichedCodeState =
+  | { status: "idle" }
+  | { status: "loading" }
+  | { status: "ok"; data: EnrichedCode; partial?: boolean }
+  | { status: "error"; message: string };
+export function useEnrichedCode(codeId: string | null): EnrichedCodeState {
+  const [state, setState] = useState<EnrichedCodeState>({ status: "idle" });
+  useEffect(() => {
+    if (codeId == null || codeId === "") {
+      setState({ status: "idle" });
+      return;
+    }
+    let cancelled = false;
+    setState({ status: "loading" });
+    codeService
+      .getFullCodeContext(codeId)
+      .then((data) => {
+        if (!cancelled) setState({ status: "ok", data });
+      })
+      .catch(() => {
+        if (cancelled) return;
+        codeService
+          .getCode(codeId)
+          .then((single) => {
+            if (!cancelled) {
+              setState({
+                status: "ok",
+                data: singleCodeResponseToEnriched(single),
+                partial: true,
+              });
+            }
+          })
+          .catch(() => {
+            if (!cancelled)
+              setState({
+                status: "error",
+                message: "Could not load full context for this code.",
+              });
+          });
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [codeId]);
+  return state;
+}

codebookly/src/features/codes/utils/exportCodesJson.ts ADDED Viewed

	@@ -0,0 +1,19 @@

+import type { CodeRecord } from "../../../types/codebook";
+export function downloadCodesJson(rows: CodeRecord[], filename: string) {
+  const payload = {
+    exportedAt: new Date().toISOString(),
+    count: rows.length,
+    codes: rows,
+  };
+  const blob = new Blob([JSON.stringify(payload, null, 2)], {
+    type: "application/json;charset=utf-8",
+  });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename.endsWith(".json") ? filename : `${filename}.json`;
+  a.click();
+  URL.revokeObjectURL(url);
+}

codebookly/src/features/codes/utils/exportEnrichedJson.ts ADDED Viewed

	@@ -0,0 +1,31 @@

+import type { EnrichedCode } from "../../../types/codebook";
+export type EnrichedExportError = { code: string; message: string };
+export function downloadEnrichedJson(
+  enriched: EnrichedCode[],
+  filename: string,
+  fetchErrors?: EnrichedExportError[]
+) {
+  const payload = {
+    exportedAt: new Date().toISOString(),
+    count: enriched.length,
+    enriched,
+    ...(fetchErrors?.length
+      ? {
+          fetchErrors,
+          note: "Some codes failed to load; see fetchErrors.",
+        }
+      : {}),
+  };
+  const blob = new Blob([JSON.stringify(payload, null, 2)], {
+    type: "application/json;charset=utf-8",
+  });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename.endsWith(".json") ? filename : `${filename}.json`;
+  a.click();
+  URL.revokeObjectURL(url);
+}

codebookly/src/features/codes/utils/fetchEnrichedForExport.ts ADDED Viewed

	@@ -0,0 +1,49 @@

+import { codeService } from "../../../services/codeApi";
+import type { EnrichedCode } from "../../../types/codebook";
+const DEFAULT_CONCURRENCY = 4;
+/**
+ * Fetches full-context payloads for each code id in parallel with a concurrency cap.
+ * Preserves successful results in the same order as `codeIds`.
+ */
+export async function fetchEnrichedForExport(
+  codeIds: string[],
+  concurrency = DEFAULT_CONCURRENCY
+): Promise<{
+  enriched: EnrichedCode[];
+  errors: { code: string; message: string }[];
+}> {
+  if (codeIds.length === 0) {
+    return { enriched: [], errors: [] };
+  }
+  const slots: (EnrichedCode | undefined)[] = new Array(codeIds.length);
+  const errors: { code: string; message: string }[] = [];
+  let nextIndex = 0;
+  async function worker() {
+    while (true) {
+      const i = nextIndex++;
+      if (i >= codeIds.length) return;
+      const id = codeIds[i];
+      try {
+        slots[i] = await codeService.getFullCodeContext(id);
+      } catch (e) {
+        errors.push({
+          code: id,
+          message: e instanceof Error ? e.message : String(e),
+        });
+      }
+    }
+  }
+  const pool = Math.min(Math.max(1, concurrency), codeIds.length);
+  await Promise.all(Array.from({ length: pool }, () => worker()));
+  const enriched = codeIds
+    .map((_, i) => slots[i])
+    .filter((x): x is EnrichedCode => x != null);
+  return { enriched, errors };
+}

codebookly/src/features/codes/utils/singleCodeToEnriched.ts ADDED Viewed

	@@ -0,0 +1,18 @@

+import type { EnrichedCode, SingleCodeResponse } from "../../../types/codebook";
+/** Builds an EnrichedCode-shaped payload for the modal when only GET /api/code is available. */
+export function singleCodeResponseToEnriched(res: SingleCodeResponse): EnrichedCode {
+  const { code, chapter_metadata } = res;
+  return {
+    code,
+    chapter_info: {
+      title: chapter_metadata.title,
+      description: chapter_metadata.description,
+      about: "",
+      chapter: code.chapter ?? "",
+    },
+    standards: [],
+    committee_designations: [],
+    index_terms: [],
+  };
+}

codebookly/src/features/definitions/components/DefinitionRow.tsx ADDED Viewed

	@@ -0,0 +1,34 @@

+import { memo } from "react";
+import type { DefinitionEntry } from "../../../types/definitions";
+export const DefinitionRow = memo(function DefinitionRow({
+  row,
+}: {
+  row: DefinitionEntry;
+}) {
+  return (
+    <tr className="border-b border-[var(--border)] hover:bg-[#252525]/80 align-top">
+      <td className="py-2 px-2 md:py-2.5 md:px-3 text-xs md:text-sm font-semibold text-[var(--text-main)] max-w-[8rem] md:max-w-[12rem]">
+        <span className="line-clamp-2" title={row.term}>
+          {row.term}
+        </span>
+      </td>
+      <td className="py-2 px-2 md:py-2.5 md:px-3 text-[0.65rem] md:text-xs text-primary uppercase whitespace-nowrap">
+        {row.letter_tag || "—"}
+      </td>
+      <td className="py-2 px-2 md:py-2.5 md:px-3 text-[0.65rem] md:text-xs text-[var(--text-muted)] max-w-[7rem] md:max-w-[10rem] hidden sm:table-cell">
+        <span className="line-clamp-2" title={row.committee_designation}>
+          {row.committee_designation}
+        </span>
+      </td>
+      <td className="py-2 px-2 md:py-2.5 md:px-3 text-xs md:text-sm text-[var(--text-main)]">
+        <span
+          className="line-clamp-3 md:line-clamp-4 leading-snug"
+          title={row.definition}
+        >
+          {row.definition}
+        </span>
+      </td>
+    </tr>
+  );
+});

codebookly/src/features/definitions/components/DefinitionsExplorer.tsx ADDED Viewed

	@@ -0,0 +1,57 @@

+import { BookOpen } from "lucide-react";
+import { useDefinitionsBrowse } from "../hooks/useDefinitionsBrowse";
+import { DefinitionsSearchForm } from "./DefinitionsSearchForm";
+import { DefinitionsTableSection } from "./DefinitionsTableSection";
+export function DefinitionsExplorer() {
+  const {
+    data,
+    loading,
+    error,
+    exportBusy,
+    runSearch,
+    goToPage,
+    exportJson,
+    rangeLabel,
+    hasResults,
+  } = useDefinitionsBrowse();
+  return (
+    <section className="space-y-4" aria-labelledby="definitions-heading">
+      <div className="flex flex-wrap items-start justify-between gap-4">
+        <div>
+          <h2
+            id="definitions-heading"
+            className="text-2xl md:text-3xl font-black text-[var(--text-h)] m-0 flex items-center gap-2"
+          >
+            <BookOpen className="shrink-0 text-[var(--primary)]" size={28} aria-hidden />
+            Definitions
+          </h2>
+          <p className="text-sm text-[var(--text-muted)] mt-2 mb-0 max-w-2xl">
+            The first page loads automatically so you can browse. Use Search to run a
+            server query over terms, definitions, and committee text (
+            <code className="text-[var(--text-main)]">GET /api/definitions?q=…</code>
+            ). Pagination keeps the same query. Download matches the results you are
+            viewing.
+          </p>
+        </div>
+      </div>
+      <DefinitionsSearchForm
+        onSearch={runSearch}
+        loading={loading}
+        exportBusy={exportBusy}
+        hasResults={hasResults}
+        onExport={exportJson}
+      />
+      <DefinitionsTableSection
+        data={data}
+        loading={loading}
+        error={error}
+        rangeLabel={rangeLabel}
+        goToPage={goToPage}
+      />
+    </section>
+  );
+}

codebookly/src/features/definitions/components/DefinitionsSearchForm.tsx ADDED Viewed

	@@ -0,0 +1,77 @@

+import { memo, useState } from "react";
+import { Download, Loader2, Search } from "lucide-react";
+type Props = {
+  onSearch: (query: string) => void;
+  loading: boolean;
+  exportBusy: boolean;
+  hasResults: boolean;
+  onExport: () => void;
+};
+export const DefinitionsSearchForm = memo(function DefinitionsSearchForm({
+  onSearch,
+  loading,
+  exportBusy,
+  hasResults,
+  onExport,
+}: Props) {
+  const [draft, setDraft] = useState("");
+  return (
+    <form
+      className="flex flex-col sm:flex-row sm:items-end gap-3 p-4 rounded-lg border border-[var(--border)] bg-[var(--bg-card)]"
+      onSubmit={(e) => {
+        e.preventDefault();
+        onSearch(draft);
+      }}
+    >
+      <div className="flex-1 min-w-0 relative">
+        <label htmlFor="def-search" className="sr-only">
+          Search definitions
+        </label>
+        <Search
+          className="absolute left-3 top-1/2 -translate-y-1/2 text-[var(--text-muted)] pointer-events-none"
+          size={18}
+          aria-hidden
+        />
+        <input
+          id="def-search"
+          type="search"
+          value={draft}
+          onChange={(e) => setDraft(e.target.value)}
+          placeholder="Search terms, definitions, committee text…"
+          className="w-full rounded-lg border border-[var(--border)] bg-[var(--bg)] pl-10 pr-3 py-2.5 text-sm text-[var(--text-main)] placeholder:text-[var(--text-muted)] focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--primary)]"
+          autoComplete="off"
+        />
+      </div>
+      <div className="flex flex-wrap items-center gap-2 shrink-0">
+        <button
+          type="submit"
+          disabled={loading}
+          className="inline-flex items-center gap-2 rounded-lg px-4 py-2.5 text-sm font-semibold border border-[var(--primary)] text-[var(--primary)] hover:bg-[#334155]/50 disabled:opacity-50 disabled:pointer-events-none"
+        >
+          {loading ? (
+            <Loader2 size={16} className="animate-spin" aria-hidden />
+          ) : (
+            <Search size={16} aria-hidden />
+          )}
+          Search
+        </button>
+        <button
+          type="button"
+          onClick={() => void onExport()}
+          disabled={exportBusy || loading || !hasResults}
+          className="inline-flex items-center gap-2 rounded-lg px-4 py-2.5 text-sm font-semibold bg-[var(--primary)] text-white hover:opacity-90 disabled:opacity-50 disabled:pointer-events-none"
+        >
+          {exportBusy ? (
+            <Loader2 size={16} className="animate-spin" aria-hidden />
+          ) : (
+            <Download size={16} aria-hidden />
+          )}
+          Download JSON
+        </button>
+      </div>
+    </form>
+  );
+});

codebookly/src/features/definitions/components/DefinitionsTableSection.tsx ADDED Viewed

	@@ -0,0 +1,102 @@

+import { memo, useMemo } from "react";
+import { ChevronLeft, ChevronRight, Loader2 } from "lucide-react";
+import type { DefinitionPageResponse } from "../../../types/definitions";
+import { DefinitionRow } from "./DefinitionRow";
+type Props = {
+  data: DefinitionPageResponse | null;
+  loading: boolean;
+  error: string | null;
+  rangeLabel: string;
+  goToPage: (p: number) => void;
+};
+export const DefinitionsTableSection = memo(function DefinitionsTableSection({
+  data,
+  loading,
+  error,
+  rangeLabel,
+  goToPage,
+}: Props) {
+  const tableRows = useMemo(
+    () =>
+      data?.items.map((row, i) => (
+        <DefinitionRow
+          key={`${data.page}-${i}-${row.term}-${row.letter_tag}`}
+          row={row}
+        />
+      )),
+    [data]
+  );
+  return (
+    <>
+      <div className="flex flex-wrap items-center justify-between gap-2 text-sm text-[var(--text-muted)] min-h-[1.5rem]">
+        <span>{rangeLabel}</span>
+        {data && data.total_pages > 1 && (
+          <div className="flex items-center gap-1">
+            <button
+              type="button"
+              disabled={data.page <= 1 || loading}
+              onClick={() => goToPage(data.page - 1)}
+              className="p-2 rounded-lg border border-[var(--border)] text-[var(--text-main)] hover:bg-[#334155] disabled:opacity-40 disabled:pointer-events-none"
+              aria-label="Previous page"
+            >
+              <ChevronLeft size={18} />
+            </button>
+            <span className="tabular-nums px-2 text-[var(--text-main)]">
+              Page {data.page} / {data.total_pages}
+            </span>
+            <button
+              type="button"
+              disabled={data.page >= data.total_pages || loading}
+              onClick={() => goToPage(data.page + 1)}
+              className="p-2 rounded-lg border border-[var(--border)] text-[var(--text-main)] hover:bg-[#334155] disabled:opacity-40 disabled:pointer-events-none"
+              aria-label="Next page"
+            >
+              <ChevronRight size={18} />
+            </button>
+          </div>
+        )}
+      </div>
+      {error && (
+        <p className="text-sm text-red-400 m-0" role="alert">
+          {error}
+        </p>
+      )}
+      <div className="relative rounded-lg border border-[var(--border)] overflow-hidden bg-[var(--bg-card)]">
+        {loading && (
+          <div
+            className="absolute inset-0 z-10 flex items-center justify-center bg-[var(--bg-card)]/70 backdrop-blur-[2px]"
+            aria-busy="true"
+            aria-label="Loading"
+          >
+            <Loader2 className="animate-spin text-[var(--primary)]" size={32} />
+          </div>
+        )}
+        <div className="overflow-x-auto">
+          <table className="w-full min-w-[640px] border-collapse text-left">
+            <thead>
+              <tr className="bg-[#252525] text-[var(--text-muted)] text-[0.65rem] md:text-xs uppercase tracking-wide">
+                <th className="py-2.5 px-2 md:px-3 font-semibold">Term</th>
+                <th className="py-2.5 px-2 md:px-3 font-semibold">Tag</th>
+                <th className="py-2.5 px-2 md:px-3 font-semibold hidden sm:table-cell">
+                  Committee
+                </th>
+                <th className="py-2.5 px-2 md:px-3 font-semibold">Definition</th>
+              </tr>
+            </thead>
+            <tbody>{tableRows}</tbody>
+          </table>
+        </div>
+        {!loading && data && data.items.length === 0 && (
+          <p className="text-sm text-[var(--text-muted)] p-8 text-center m-0">
+            No definitions match your search.
+          </p>
+        )}
+      </div>
+    </>
+  );
+});

codebookly/src/features/definitions/hooks/useDefinitionsBrowse.ts ADDED Viewed

	@@ -0,0 +1,102 @@

+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import axios from "axios";
+import { definitionsBrowse } from "../services/definitionsBrowse";
+import type { DefinitionPageResponse } from "../../../types/definitions";
+const PAGE_SIZE = 24;
+export function useDefinitionsBrowse() {
+  const [appliedQ, setAppliedQ] = useState("");
+  const [data, setData] = useState<DefinitionPageResponse | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [exportBusy, setExportBusy] = useState(false);
+  const abortRef = useRef<AbortController | null>(null);
+  const loadPage = useCallback(async (targetPage: number, q: string) => {
+    abortRef.current?.abort();
+    const ac = new AbortController();
+    abortRef.current = ac;
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await definitionsBrowse.fetchPage(
+        {
+          page: targetPage,
+          page_size: PAGE_SIZE,
+          q: q || undefined,
+        },
+        ac.signal
+      );
+      if (ac.signal.aborted) return;
+      setData(res);
+      setAppliedQ(q);
+    } catch (err) {
+      if (
+        ac.signal.aborted ||
+        axios.isCancel(err) ||
+        (axios.isAxiosError(err) && err.code === "ERR_CANCELED")
+      ) {
+        return;
+      }
+      setError(
+        err instanceof Error ? err.message : "Failed to load definitions"
+      );
+      setData(null);
+    } finally {
+      if (!ac.signal.aborted) setLoading(false);
+    }
+  }, []);
+  useEffect(() => {
+    void loadPage(1, "");
+  }, [loadPage]);
+  const runSearch = useCallback(
+    (q: string) => {
+      void loadPage(1, q.trim());
+    },
+    [loadPage]
+  );
+  const goToPage = useCallback(
+    (nextPage: number) => {
+      if (!data || nextPage < 1 || nextPage > data.total_pages) return;
+      void loadPage(nextPage, appliedQ);
+    },
+    [data, appliedQ, loadPage]
+  );
+  const exportJson = useCallback(async () => {
+    setExportBusy(true);
+    try {
+      await definitionsBrowse.downloadExport({
+        q: appliedQ || undefined,
+      });
+    } finally {
+      setExportBusy(false);
+    }
+  }, [appliedQ]);
+  const rangeLabel = useMemo(() => {
+    if (!data) return loading ? "Loading…" : "";
+    if (data.total === 0) return "No results";
+    const start = (data.page - 1) * data.page_size + 1;
+    const end = Math.min(data.page * data.page_size, data.total);
+    return `${start}–${end} of ${data.total}`;
+  }, [data, loading]);
+  return {
+    data,
+    loading,
+    error,
+    exportBusy,
+    runSearch,
+    goToPage,
+    exportJson,
+    rangeLabel,
+    hasResults: data != null,
+  };
+}

codebookly/src/features/definitions/services/definitionsBrowse.ts ADDED Viewed

	@@ -0,0 +1,18 @@

+import type { DefinitionPageResponse } from "../../../types/definitions";
+import {
+  definitionsService,
+  type DefinitionsPageParams,
+} from "../../../services/definitionsApi";
+export const definitionsBrowse = {
+  fetchPage(
+    params: DefinitionsPageParams,
+    signal?: AbortSignal
+  ): Promise<DefinitionPageResponse> {
+    return definitionsService.getPage(params, { signal });
+  },
+  downloadExport(params: { q?: string; letter_tag?: string }): Promise<void> {
+    return definitionsService.downloadExport(params);
+  },
+};

codebookly/src/features/layout/SectionChapterBanner.tsx ADDED Viewed

	@@ -0,0 +1,33 @@

+import type { SectionChapterMetadata } from "../../types/codebook";
+type Props = {
+  meta: SectionChapterMetadata;
+  contextLabel?: string;
+};
+export function SectionChapterBanner({
+  meta,
+  contextLabel = "Chapter context",
+}: Props) {
+  return (
+    <section
+      className="mb-8 rounded-xl border border-border-ui bg-card px-5 py-5 md:px-8 md:py-6"
+      aria-labelledby="section-chapter-banner-title"
+    >
+      <p className="text-[0.7rem] uppercase tracking-wider text-primary font-semibold m-0 mb-2">
+        {contextLabel}
+      </p>
+      <h2
+        id="section-chapter-banner-title"
+        className="text-xl md:text-2xl font-extrabold text-text-main m-0"
+      >
+        {meta.title}
+      </h2>
+      {meta.description ? (
+        <p className="text-sm md:text-base text-text-muted mt-3 mb-0 leading-relaxed">
+          {meta.description}
+        </p>
+      ) : null}
+    </section>
+  );
+}

codebookly/src/features/layout/SideBar.tsx ADDED Viewed

	@@ -0,0 +1,246 @@

+import { useCallback, useState } from "react";
+import {
+  BookOpen,
+  Building2,
+  ChevronLeft,
+  Layers,
+  List,
+  Menu,
+} from "lucide-react";
+import { CODEBOOKLY_ICON_SRC } from "../../branding";
+import type { Agency, CommitteeDesignation } from "../../types/codebook";
+import { SidebarAccordion } from "./SidebarAccordion";
+import { SIDEBAR_SUB_LINK, sidebarNavBtnClass } from "./sidebarTokens";
+type Props = {
+  sections: { section: string; title: string }[];
+  chapters: { chapter: string; title: string }[];
+  designations: CommitteeDesignation[];
+  agencies: Agency[];
+  onSectionSelect: (sectionCode: string) => void;
+  onChapterSelect: (chapterKey: string) => void;
+  onDesignationSelect: (d: CommitteeDesignation) => void;
+  onAgencySelect: (a: Agency) => void;
+  onDefinitionsSelect: () => void;
+  definitionsActive?: boolean;
+};
+const SCROLL_PANEL = "max-h-[min(50vh,20rem)] overflow-y-auto custom-scrollbar";
+export default function SideBar({
+  sections,
+  chapters,
+  designations: _designations,
+  agencies,
+  onSectionSelect,
+  onChapterSelect,
+  onDesignationSelect: _onDesignationSelect,
+  onAgencySelect,
+  onDefinitionsSelect,
+  definitionsActive = false,
+}: Props) {
+  const [openMenu, setOpenMenu] = useState<string | null>(null);
+  const [isExpanded, setIsExpanded] = useState(true);
+  const expandAndToggle = useCallback((menuName: string) => {
+    setIsExpanded(true);
+    setOpenMenu((prev) => (prev === menuName ? null : menuName));
+  }, []);
+  return (
+    <aside
+      className={`fixed top-0 left-0 h-screen bg-[var(--bg-card)] border-r border-[var(--border)] flex flex-col z-50
+      ${isExpanded ? "w-72" : "w-20"}`}
+    >
+      <div
+        className={`h-20 border-b border-[var(--border)] flex items-center gap-2 shrink-0 ${
+          isExpanded
+            ? "px-6 justify-between flex-row"
+            : "px-2 flex-col justify-center"
+        }`}
+      >
+        <div
+          className={`flex items-center gap-3 min-w-0 ${
+            isExpanded ? "flex-1" : "justify-center"
+          }`}
+        >
+          {isExpanded ? (
+            <span className="text-xl font-bold tracking-tighter text-[var(--text-main)] truncate">
+              <img
+                src={CODEBOOKLY_ICON_SRC}
+                alt=""
+                width={500}
+                height={500}
+                className="size-24 shrink-0"
+                decoding="async"
+              />
+            </span>
+          ) : null}
+        </div>
+        <button
+          type="button"
+          onClick={() => setIsExpanded((e) => !e)}
+          className="p-2 rounded-lg hover:bg-[#334155] text-[var(--text-muted)] hover:text-[var(--text-main)]"
+          aria-label={isExpanded ? "Collapse sidebar" : "Expand sidebar"}
+        >
+          {isExpanded ? <ChevronLeft size={20} /> : <Menu size={20} />}
+        </button>
+      </div>
+      <nav className="flex-1 overflow-y-auto p-4 space-y-2 custom-scrollbar">
+        <div className="space-y-1">
+          <button
+            type="button"
+            onClick={() => {
+              onDefinitionsSelect();
+              setOpenMenu(null);
+            }}
+            title={!isExpanded ? "Definitions" : undefined}
+            className={sidebarNavBtnClass(!!definitionsActive, isExpanded)}
+          >
+            <div className="flex items-center gap-3">
+              <BookOpen size={22} className="shrink-0" aria-hidden />
+              {isExpanded && (
+                <span className="font-semibold text-sm tracking-wide">
+                  Definitions
+                </span>
+              )}
+            </div>
+            {isExpanded && <span className="w-4 shrink-0" aria-hidden />}
+          </button>
+        </div>
+        <SidebarAccordion
+          menuId="sections"
+          label="Sections"
+          icon={<Layers size={22} className="shrink-0" aria-hidden />}
+          isNavExpanded={isExpanded}
+          openMenu={openMenu}
+          onToggle={expandAndToggle}
+        >
+          {sections.map((section) => (
+            <button
+              type="button"
+              key={section.section}
+              className={`${SIDEBAR_SUB_LINK} w-full text-left border-0 bg-transparent cursor-pointer font-inherit`}
+              onClick={() => onSectionSelect(section.section)}
+            >
+              <div className="flex flex-row items-center gap-3 border-b border-[var(--border)] pb-2">
+                <span className=" text-[var(--text-main)]">
+                  {section.section}
+                </span>
+                <span className="block text-[0.75rem] text-[var(--text-muted)]">
+                  {section.title}
+                </span>
+              </div>
+            </button>
+          ))}
+        </SidebarAccordion>
+        <SidebarAccordion
+          menuId="chapters"
+          label="Chapters"
+          icon={<List size={22} className="shrink-0" aria-hidden />}
+          isNavExpanded={isExpanded}
+          openMenu={openMenu}
+          onToggle={expandAndToggle}
+        >
+          {chapters.map((chapter) => (
+            <button
+              type="button"
+              key={chapter.chapter}
+              className={`${SIDEBAR_SUB_LINK} w-full text-left border-0 bg-transparent cursor-pointer font-inherit`}
+              onClick={() => onChapterSelect(chapter.chapter)}
+            >
+              <div className="flex flex-row items-center gap-3 border-b border-[var(--border)] pb-2">
+                <span className=" text-[var(--text-main)]">
+                  {chapter.chapter}
+                </span>
+                <span className="block text-[0.75rem] text-[var(--text-muted)]">
+                  {chapter.title}
+                </span>
+              </div>
+            </button>
+          ))}
+        </SidebarAccordion>
+        {/* <SidebarAccordion
+          menuId="designations"
+          label="Designations"
+          icon={<Tags size={22} className="shrink-0" aria-hidden />}
+          isNavExpanded={isExpanded}
+          openMenu={openMenu}
+          onToggle={expandAndToggle}
+          collapsedTitle="Designations"
+          panelClassName={SCROLL_PANEL}
+        >
+          {designations.length === 0 ? (
+            <span
+              className={`${SIDEBAR_SUB_LINK} text-[var(--text-muted)] cursor-default`}
+            >
+              None loaded
+            </span>
+          ) : (
+            designations.map((d) => (
+              <button
+                type="button"
+                key={d.letter_tag}
+                className={`${SIDEBAR_SUB_LINK} w-full text-left border-0 bg-transparent cursor-pointer font-inherit`}
+                title={d.description || undefined}
+                onClick={() => onDesignationSelect(d)}
+              >
+                <span className="block text-[0.75rem] text-[var(--text-muted)] mt-0.5 line-clamp-2">
+                  {d.description}
+                </span>
+                {d.description ? (
+                  <span className="font-semibold text-[var(--text-main)]">
+                    {d.letter_tag}
+                  </span>
+                ) : null}
+              </button>
+            ))
+          )}
+        </SidebarAccordion> */}
+        <SidebarAccordion
+          menuId="agencies"
+          label="Referenced Standards"
+          icon={<Building2 size={22} className="shrink-0" aria-hidden />}
+          isNavExpanded={isExpanded}
+          openMenu={openMenu}
+          onToggle={expandAndToggle}
+          collapsedTitle="Agencies"
+          panelClassName={SCROLL_PANEL}
+        >
+          {agencies.length === 0 ? (
+            <span
+              className={`${SIDEBAR_SUB_LINK} text-[var(--text-muted)] cursor-default`}
+            >
+              None loaded
+            </span>
+          ) : (
+            agencies.map((a) => (
+              <button
+                type="button"
+                key={a.agency}
+                className={`${SIDEBAR_SUB_LINK} w-full text-left border-0 bg-transparent cursor-pointer font-inherit`}
+                title={a.agency_info || undefined}
+                onClick={() => onAgencySelect(a)}
+              >
+                <span className="font-semibold text-[var(--text-main)]">
+                  {a.agency}
+                </span>
+                {a.agency_info ? (
+                  <span className="block text-[0.75rem] text-[var(--text-muted)] mt-0.5 line-clamp-2">
+                    {a.agency_info}
+                  </span>
+                ) : null}
+              </button>
+            ))
+          )}
+        </SidebarAccordion>
+      </nav>
+    </aside>
+  );
+}

codebookly/src/features/layout/SidebarAccordion.tsx ADDED Viewed

	@@ -0,0 +1,63 @@

+import type { ReactNode } from "react";
+import { ChevronDown } from "lucide-react";
+import { sidebarNavBtnClass } from "./sidebarTokens";
+type Props = {
+  menuId: string;
+  label: string;
+  icon: ReactNode;
+  isNavExpanded: boolean;
+  openMenu: string | null;
+  onToggle: (menuId: string) => void;
+  collapsedTitle?: string;
+  /** e.g. max-h scroll for long lists */
+  panelClassName?: string;
+  children: ReactNode;
+};
+export function SidebarAccordion({
+  menuId,
+  label,
+  icon,
+  isNavExpanded,
+  openMenu,
+  onToggle,
+  collapsedTitle,
+  panelClassName,
+  children,
+}: Props) {
+  const isOpen = openMenu === menuId;
+  return (
+    <div className="space-y-1">
+      <button
+        type="button"
+        onClick={() => onToggle(menuId)}
+        title={!isNavExpanded ? collapsedTitle : undefined}
+        className={sidebarNavBtnClass(isOpen && isNavExpanded, isNavExpanded)}
+      >
+        <div className="flex items-center gap-3">
+          {icon}
+          {isNavExpanded && (
+            <span className="font-semibold text-sm tracking-wide">{label}</span>
+          )}
+        </div>
+        {isNavExpanded && (
+          <ChevronDown
+            size={16}
+            className={isOpen ? "rotate-180" : "opacity-40"}
+            aria-hidden
+          />
+        )}
+      </button>
+      {isNavExpanded && isOpen && (
+        <div
+          className={`ml-4 flex flex-col gap-1 border-l border-[var(--border)] pl-4 py-1 ${panelClassName ?? ""}`}
+        >
+          {children}
+        </div>
+      )}
+    </div>
+  );
+}

codebookly/src/features/layout/sidebarTokens.ts ADDED Viewed

	@@ -0,0 +1,9 @@

+/** Shared sidebar list / accordion styling */
+export const SIDEBAR_SUB_LINK =
+  "text-sm py-2 px-3 rounded-md hover:text-[var(--primary)] hover:bg-[#334155] text-[var(--text-muted)]";
+export function sidebarNavBtnClass(active: boolean, isExpanded: boolean) {
+  return `w-full flex items-center p-3 rounded-lg group
+    ${active ? "bg-[#334155] text-[var(--primary)]" : "text-[var(--text-muted)] hover:bg-[#252525] hover:text-[var(--text-main)]"}
+    ${isExpanded ? "justify-between" : "justify-center"}`;
+}

codebookly/src/hooks/useCodebookApp.ts ADDED Viewed

	@@ -0,0 +1,249 @@

+import { useCallback, useEffect, useRef, useState } from "react";
+import { codeService } from "../services/codeApi";
+import type {
+  Agency,
+  CodeRecord,
+  CommitteeDesignation,
+  SectionChapterMetadata,
+} from "../types/codebook";
+export type MainView = "codes" | "definitions";
+function clearBrowseMeta(
+  setSection: (v: SectionChapterMetadata | null) => void,
+  setDesignation: (v: SectionChapterMetadata | null) => void,
+  setAgency: (v: SectionChapterMetadata | null) => void
+) {
+  setSection(null);
+  setDesignation(null);
+  setAgency(null);
+}
+/**
+ * Shell state: navigation data, codes list, and handlers. Bootstrap uses one
+ * parallel round-trip (Promise.allSettled) instead of sequential fetches.
+ */
+export function useCodebookApp() {
+  const browseRequestIdRef = useRef(0);
+  const [mainView, setMainView] = useState<MainView>("codes");
+  const [codes, setCodes] = useState<CodeRecord[]>([]);
+  const [sectionChapterMeta, setSectionChapterMeta] =
+    useState<SectionChapterMetadata | null>(null);
+  const [designationMeta, setDesignationMeta] =
+    useState<SectionChapterMetadata | null>(null);
+  const [agencyMeta, setAgencyMeta] = useState<SectionChapterMetadata | null>(
+    null
+  );
+  const [sections, setSections] = useState<{ section: string; title: string }[]>(
+    []
+  );
+  const [chapters, setChapters] = useState<{ chapter: string; title: string }[]>(
+    []
+  );
+  const [designations, setDesignations] = useState<CommitteeDesignation[]>([]);
+  const [agencies, setAgencies] = useState<Agency[]>([]);
+  const [initialBrowseLoading, setInitialBrowseLoading] = useState(true);
+  const [codesBrowseLoading, setCodesBrowseLoading] = useState(false);
+  const nextBrowseRequestId = useCallback(() => {
+    browseRequestIdRef.current += 1;
+    return browseRequestIdRef.current;
+  }, []);
+  useEffect(() => {
+    let cancelled = false;
+    (async () => {
+      try {
+        const [
+          codesResult,
+          sectionsResult,
+          chaptersResult,
+          designationsResult,
+          agenciesResult,
+        ] = await Promise.allSettled([
+          codeService.getCodes(),
+          codeService.getSections(),
+          codeService.getChapters(),
+          codeService.getCommitteeDesignations(),
+          codeService.getAgencies(),
+        ]);
+        if (cancelled) return;
+        if (codesResult.status === "fulfilled") {
+          setCodes(codesResult.value ?? []);
+          clearBrowseMeta(
+            setSectionChapterMeta,
+            setDesignationMeta,
+            setAgencyMeta
+          );
+        }
+        if (sectionsResult.status === "fulfilled") {
+          setSections(sectionsResult.value ?? []);
+        }
+        if (chaptersResult.status === "fulfilled") {
+          setChapters(chaptersResult.value ?? []);
+        }
+        if (designationsResult.status === "fulfilled") {
+          setDesignations(designationsResult.value ?? []);
+        } else {
+          setDesignations([]);
+        }
+        if (agenciesResult.status === "fulfilled") {
+          setAgencies(agenciesResult.value ?? []);
+        } else {
+          setAgencies([]);
+        }
+      } finally {
+        if (!cancelled) {
+          setInitialBrowseLoading(false);
+        }
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+  const handleSectionSelect = useCallback(
+    async (sectionCode: string) => {
+      const reqId = nextBrowseRequestId();
+      setMainView("codes");
+      setCodesBrowseLoading(true);
+      setCodes([]);
+      setSectionChapterMeta(null);
+      setDesignationMeta(null);
+      setAgencyMeta(null);
+      try {
+        const data = await codeService.getSectionData(sectionCode);
+        if (browseRequestIdRef.current !== reqId) return;
+        setCodes(data.codes ?? []);
+        const cm = data.chapter_metadata;
+        setSectionChapterMeta(
+          cm
+            ? { title: cm.title, description: cm.description ?? "" }
+            : null
+        );
+      } catch {
+        if (browseRequestIdRef.current !== reqId) return;
+        setCodes([]);
+        setSectionChapterMeta(null);
+      } finally {
+        if (browseRequestIdRef.current === reqId) {
+          setCodesBrowseLoading(false);
+        }
+      }
+    },
+    [nextBrowseRequestId]
+  );
+  const handleDesignationSelect = useCallback(
+    async (d: CommitteeDesignation) => {
+      const reqId = nextBrowseRequestId();
+      setMainView("codes");
+      setCodesBrowseLoading(true);
+      setCodes([]);
+      setSectionChapterMeta(null);
+      setAgencyMeta(null);
+      setDesignationMeta({
+        title: d.letter_tag,
+        description: d.description ?? "",
+      });
+      try {
+        const list = await codeService.getCodesByDesignation(d.letter_tag);
+        if (browseRequestIdRef.current !== reqId) return;
+        setCodes(list ?? []);
+      } catch {
+        if (browseRequestIdRef.current !== reqId) return;
+        setCodes([]);
+      } finally {
+        if (browseRequestIdRef.current === reqId) {
+          setCodesBrowseLoading(false);
+        }
+      }
+    },
+    [nextBrowseRequestId]
+  );
+  const handleAgencySelect = useCallback(
+    async (a: Agency) => {
+      const reqId = nextBrowseRequestId();
+      setMainView("codes");
+      setCodesBrowseLoading(true);
+      setCodes([]);
+      setSectionChapterMeta(null);
+      setDesignationMeta(null);
+      setAgencyMeta({
+        title: a.agency,
+        description: a.agency_info ?? "",
+      });
+      try {
+        const enriched = await codeService.getCodesByAgency(a.agency);
+        if (browseRequestIdRef.current !== reqId) return;
+        setCodes((enriched ?? []).map((row) => row.code));
+      } catch {
+        if (browseRequestIdRef.current !== reqId) return;
+        setCodes([]);
+      } finally {
+        if (browseRequestIdRef.current === reqId) {
+          setCodesBrowseLoading(false);
+        }
+      }
+    },
+    [nextBrowseRequestId]
+  );
+  const handleChapterSelect = useCallback(
+    async (chapterKey: string) => {
+      const reqId = nextBrowseRequestId();
+      setMainView("codes");
+      setCodesBrowseLoading(true);
+      setCodes([]);
+      clearBrowseMeta(
+        setSectionChapterMeta,
+        setDesignationMeta,
+        setAgencyMeta
+      );
+      try {
+        const meta = await codeService.searchChapterOrAppendix(chapterKey);
+        if (browseRequestIdRef.current !== reqId) return;
+        const id =
+          meta.chapter != null && meta.chapter !== ""
+            ? String(meta.chapter)
+            : meta.appendix != null && meta.appendix !== ""
+              ? String(meta.appendix)
+              : chapterKey;
+        const list = await codeService.getCodesByChapter(id);
+        if (browseRequestIdRef.current !== reqId) return;
+        setCodes(list ?? []);
+      } catch {
+        if (browseRequestIdRef.current !== reqId) return;
+        setCodes([]);
+      } finally {
+        if (browseRequestIdRef.current === reqId) {
+          setCodesBrowseLoading(false);
+        }
+      }
+    },
+    [nextBrowseRequestId]
+  );
+  const codesAreaLoading = initialBrowseLoading || codesBrowseLoading;
+  return {
+    mainView,
+    setMainView,
+    codes,
+    codesAreaLoading,
+    sectionChapterMeta,
+    designationMeta,
+    agencyMeta,
+    sections,
+    chapters,
+    designations,
+    agencies,
+    handleSectionSelect,
+    handleChapterSelect,
+    handleDesignationSelect,
+    handleAgencySelect,
+  };
+}

codebookly/src/index.css ADDED Viewed

	@@ -0,0 +1,34 @@

+@import "tailwindcss";
+/* Keep your variables, but remove the tag selectors like h1 { font-size: 56px } */
+:root {
+  --text: #6b6375;
+  --text-h: #08060d;
+  --bg: #fff;
+  --border: #e5e4e7;
+  --accent: #aa3bff;
+  /* ... keep other vars ... */
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --text: #9ca3af;
+    --text-h: #f3f4f6;
+    --bg: #16171d;
+  }
+}
+@theme {
+  --color-primary: #3b82f6;
+  --color-card: #1e1e1e;
+  --color-border-ui: #334155;
+  --color-text-main: #ececec;
+  --color-text-muted: #94a3b8;
+}
+body {
+  margin: 0;
+  background-color: var(--bg);
+  color: var(--text);
+  font-family: system-ui, sans-serif;
+}

codebookly/src/main.tsx ADDED Viewed

	@@ -0,0 +1,22 @@

+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { CODEBOOKLY_ICON_SRC } from "./branding";
+import "./index.css";
+import App from "./App.tsx";
+{
+  let link = document.querySelector<HTMLLinkElement>('link[rel="icon"]');
+  if (!link) {
+    link = document.createElement("link");
+    link.rel = "icon";
+    document.head.appendChild(link);
+  }
+  link.type = "image/webp";
+  link.href = CODEBOOKLY_ICON_SRC;
+}
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

codebookly/src/services/apiClient.ts ADDED Viewed

	@@ -0,0 +1,7 @@

+import axios from "axios";
+const API_BASE_URL = "http://127.0.0.1:8000";
+export const apiClient = axios.create({
+  baseURL: API_BASE_URL,
+});

codebookly/src/services/apiService.ts ADDED Viewed

	@@ -0,0 +1,10 @@

+/**
+ * Barrel re-exports — import from `codeApi` / `definitionsApi` for clearer boundaries.
+ */
+export { apiClient } from "./apiClient";
+export {
+  codeService,
+  CODES_BY_AGENCY_LIMIT,
+  CODES_BY_DESIGNATION_LIMIT,
+} from "./codeApi";
+export { definitionsService, type DefinitionsPageParams } from "./definitionsApi";

codebookly/src/services/codeApi.ts ADDED Viewed

	@@ -0,0 +1,74 @@

+import type {
+  Agency,
+  CodeRecord,
+  CommitteeDesignation,
+  EnrichedCode,
+  SectionDataResponse,
+  SingleCodeResponse,
+} from "../types/codebook";
+import { apiClient } from "./apiClient";
+/** Server default is 10; use a higher cap until the API paginates. */
+export const CODES_BY_DESIGNATION_LIMIT = 2000;
+/**
+ * get-codes-by-agency runs full enrichment per row on the server — keep moderate
+ * until the API returns plain codes or paginates.
+ */
+export const CODES_BY_AGENCY_LIMIT = 150;
+export const codeService = {
+  getCodes: () => apiClient.get<CodeRecord[]>("/api/codes").then((res) => res.data),
+  getChapters: () => apiClient.get("/api/chapters").then((res) => res.data),
+  getSections: () =>
+    apiClient.get("/api/list-sections").then((res) => res.data),
+  getSectionData: (section: string) =>
+    apiClient
+      .get<SectionDataResponse>(
+        `/api/sections/${encodeURIComponent(section)}`
+      )
+      .then((res) => res.data),
+  searchChapterOrAppendix: (search: string) =>
+    apiClient
+      .get(`/api/search-chapter-or-appendix/${encodeURIComponent(search)}`)
+      .then((res) => res.data),
+  getCodesByChapter: (chapter: string) =>
+    apiClient
+      .get<CodeRecord[]>(
+        `/api/get-codes-by-chapter/${encodeURIComponent(chapter)}`
+      )
+      .then((res) => res.data),
+  getCommitteeDesignations: () =>
+    apiClient
+      .get<CommitteeDesignation[]>("/api/committee-designations")
+      .then((res) => res.data),
+  getCodesByDesignation: (
+    designation: string,
+    limit = CODES_BY_DESIGNATION_LIMIT
+  ) =>
+    apiClient
+      .get<CodeRecord[]>(
+        `/api/get-codes-by-designation/${encodeURIComponent(designation)}`,
+        { params: { limit } }
+      )
+      .then((res) => res.data),
+  getAgencies: () =>
+    apiClient.get<Agency[]>("/api/agencies").then((res) => res.data),
+  getCodesByAgency: (agency: string, limit = CODES_BY_AGENCY_LIMIT) =>
+    apiClient
+      .get<EnrichedCode[]>(
+        `/api/get-codes-by-agency/${encodeURIComponent(agency)}`,
+        { params: { limit } }
+      )
+      .then((res) => res.data),
+  getCode: (code: string) =>
+    apiClient
+      .get<SingleCodeResponse>(`/api/code/${encodeURIComponent(code)}`)
+      .then((res) => res.data),
+  getFullCodeContext: (code: string) =>
+    apiClient
+      .get<EnrichedCode>(
+        `/api/codes-full-context/${encodeURIComponent(code)}`
+      )
+      .then((res) => res.data),
+};

codebookly/src/services/definitionsApi.ts ADDED Viewed

	@@ -0,0 +1,40 @@

+import type { DefinitionPageResponse } from "../types/definitions";
+import { apiClient } from "./apiClient";
+export type DefinitionsPageParams = {
+  page?: number;
+  page_size?: number;
+  q?: string;
+  letter_tag?: string;
+};
+export const definitionsService = {
+  getPage: (params: DefinitionsPageParams, config?: { signal?: AbortSignal }) =>
+    apiClient
+      .get<DefinitionPageResponse>("/api/definitions", {
+        params: {
+          page: params.page ?? 1,
+          page_size: params.page_size ?? 24,
+          q: params.q,
+          letter_tag: params.letter_tag,
+        },
+        signal: config?.signal,
+      })
+      .then((res) => res.data),
+  downloadExport: async (params: { q?: string; letter_tag?: string }) => {
+    const res = await apiClient.get<Blob>("/api/definitions/export", {
+      params: {
+        q: params.q,
+        letter_tag: params.letter_tag,
+      },
+      responseType: "blob",
+    });
+    const url = URL.createObjectURL(res.data);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = `definitions-export-${new Date().toISOString().slice(0, 10)}.json`;
+    a.click();
+    URL.revokeObjectURL(url);
+  },
+};

codebookly/src/types/code.d.ts ADDED Viewed

File without changes

codebookly/src/types/codebook.ts ADDED Viewed

	@@ -0,0 +1,75 @@

+/** Shipped with GET /api/sections/{section} as `chapter_metadata` */
+export interface SectionChapterMetadata {
+  title: string;
+  description: string;
+}
+/** Mirrors backend `schemas.Code` */
+export interface CodeRecord {
+  entry_type: string;
+  letter_tag: string;
+  code: string;
+  chapter: string;
+  parent_code: string;
+  root_code: string;
+  title: string;
+  figure: string;
+  table: string;
+  content: string;
+  section_code: string;
+  section_title: string;
+  sort_index: number;
+}
+/** GET /api/sections/{section} */
+export interface SectionDataResponse {
+  chapter_metadata: SectionChapterMetadata;
+  codes: CodeRecord[];
+}
+/** GET /api/code/{code} */
+export interface SingleCodeResponse {
+  chapter_metadata: SectionChapterMetadata;
+  code: CodeRecord;
+}
+export interface ChapterInfo {
+  title: string;
+  description: string;
+  about: string;
+  chapter: string;
+}
+/** Subset returned by full-context endpoint (agency, standard_id, definition). */
+export interface StandardRef {
+  agency: string;
+  standard_id: string;
+  definition: string;
+}
+export interface Agency {
+  agency: string;
+  agency_info: string;
+}
+export interface CommitteeDesignation {
+  letter_tag: string;
+  description: string;
+}
+export interface IndexReference {
+  id: number;
+  term: string;
+  label: string;
+  ref_id: string;
+  ref_type: string;
+  breadcrumb: string;
+}
+export interface EnrichedCode {
+  code: CodeRecord;
+  chapter_info: ChapterInfo;
+  standards: StandardRef[];
+  committee_designations: CommitteeDesignation[];
+  index_terms: IndexReference[];
+}

codebookly/src/types/constants.ts ADDED Viewed

	@@ -0,0 +1,7 @@

+export const COLORS = {
+  primary: "#3b82f6",
+  textMain: "#ececec",
+  textMuted: "#94a3b8",
+  bgCard: "#1e1e1e",
+  border: "#334155",
+} as const;

codebookly/src/types/definitions.ts ADDED Viewed

	@@ -0,0 +1,14 @@

+export interface DefinitionEntry {
+  definition: string;
+  term: string;
+  letter_tag: string;
+  committee_designation: string;
+}
+export interface DefinitionPageResponse {
+  items: DefinitionEntry[];
+  total: number;
+  page: number;
+  page_size: number;
+  total_pages: number;
+}

codebookly/src/types/navbar.ts ADDED Viewed

	@@ -0,0 +1,27 @@

+export type NavbarBrandConfig = {
+  title: string;
+  href: string;
+};
+export type NavbarBrowseOption = {
+  kind: string;
+  label: string;
+  itemPlaceholder: string;
+};
+export type NavbarBrowseCopy = {
+  regionAriaLabel: string;
+  typeColumnLabel: string;
+  contentTypeSelectAriaLabel: string;
+};
+export type NavbarBrowseConfig = {
+  options: NavbarBrowseOption[];
+  copy: NavbarBrowseCopy;
+};
+export type NavbarProps = {
+  brand: NavbarBrandConfig;
+  browse?: NavbarBrowseConfig;
+  className?: string;
+};