@columbia-libraries/cul-toolkit 5.0.5 → 5.2.0

package/README.md

@@ -2,43 +2,44 @@
 
 _Version 5.x_
 
-## Development requirements
+## Requirements
 ```
-nodejs >= v20
-npm >= 10.2
+nodejs >= v22
 ```
 
-## Vite for development
-Dev server runs on http://localhost:8181 and auto-recompiles code when resources change.
+## Development
+Start the Vite dev server:
 ```
-npm start
+npm run dev
 ```
-Preview server runs on http://localhost:4173 and serves the built dist/ dir.
+The app is available at http://localhost:5173
+
+## Preview production build
+Serve the production build locally:
 ```
 npm run preview
 ```
 
-## Vite Build Instructions
-Vite will bundle code and copy public/ files for distribution into the dist/ dir.
-```
-npm install # run the first time you want to build, or if the package-lock.json file has changed
-```
-```
+## Build
+Install dependencies and build:
+```bash
+npm install
 npm run build
 ```
+The output is written to the dist/ directory.
 
 ## Deployment requirements
 
 Local machine:
 ```
-ruby >= 2.5.3 (we currently have a .ruby-version file requiring 2.5.3)
+ruby >= 2.7.5 (we currently have a .ruby-version file requiring 2.7.5)
 bundler
 ```
 
 Remote deployment server:
 ```
-node >= 10.17.0
-yarn >= 1.19.1
+node >= 22
+npm >= 10
 ```
 ## Deploying a versioned release
 
@@ -59,3 +60,247 @@ cap dev deploy # or replace "dev" with "test" or "prod"
 
 Note: In order to deploy, you need to have your public key in the remote server user's authorized_keys file on your dev/test/prod hosts.
 
+
+---
+
+## CUL Menu Usage
+
+CUL Menu is a portable BS5-compatible menu system that renders two styles of navigational menus from an authoritative JSON data source.
+
+Purpose:
+
+* **Menu content changes more often than apps**
+* Avoid editing/redeploying multiple sites for a simple label or link change
+* Centralized menu control
+* Safe degradation when offline or blocked by CORS
+
+Supports:
+
+* **Runtime menu updates** (no rebuild required)
+* **Graceful fallback** to a bundled example menu
+* **Multiple render styles** (vertical collapse menu (CUL global menu / v5 theme), navbar (lweb v3 style))
+
+Features:
+
+* Fetch menu JSON from **remote authoritative source**
+* Fallback to a **bundled example menu** if remote fails
+* Cache-busting via app version
+* Works in: Dynamic/JS apps, Static HTML pages, WP themes, etc.
+
+Requirements:
+
+* Bootstrap 5 CSS (**part of CUL Toolkit v5!**)
+* Bootstrap 5 JS (dropdowns / collapse) (**part of CUL Toolkit v5!**)
+* Modern browser (ES2019+)
+
+---
+
+### CUL Menu JSON Format
+
+```json
+{
+  "Services & Tools": [
+    {
+      "href": "https://library.columbia.edu/services.html",
+      "value": "Services & Tools"
+    },
+  ],
+  "Libraries": [
+    {
+      "href": "https://library.columbia.edu/libraries.html",
+      "value": "Libraries & Affiliates"
+    },
+    {
+      "href": "https://library.columbia.edu/libraries/avery.html",
+      "value": "Avery Architectural & Fine Arts Library"
+    },
+  ]
+}
+```
+
+### Usage in this app (CUL Toolkit examples, etc)
+
+#### Environmental Variable 
+
+Create root `.env`:
+
+```env
+VITE_CUL_MENU_URL=https://toolkit.library.columbia.edu/v5/assets/cul-main-menu.json
+```
+
+#### main.js
+
+```js
+import { makeCULmenu } from './culmenu.js';
+import { makeCULNavbarMenu } from './culmenu-navbar.js';
+
+const MENU_URL = import.meta.env.VITE_CUL_MENU_URL || undefined;
+
+makeCULmenu(MENU_URL);
+makeCULNavbarMenu('[data-cul-navbar]', MENU_URL);
+```
+
+---
+
+### Markup
+
+#### Vertical / Collapse Menu
+
+```html
+<nav data-cul-menu class="cul-menu-loading"></nav>
+```
+
+#### Navbar / Dropdown Menu
+
+```html
+<nav
+  class="navbar navbar-expand-lg cul-menu-loading"
+  data-cul-navbar
+  data-menu-id="main"
+>
+  <ul class="navbar-nav"></ul>
+</nav>
+```
+
+The JS will replace the contents at runtime.
+
+---
+
+### Loading & Fallback Behavior
+
+1. Attempt to fetch menu from:
+
+   * `VITE_CUL_MENU_URL` (if provided)
+2. If fetch fails:
+
+   * Use bundled example menu (`cul-main-menu.json`)
+3. Cache-busting is applied using app version
+
+Console warning when fallback is used:
+
+```
+[CUL Menu] Remote menu unavailable, using bundled example.
+```
+
+---
+
+### Using the Bundle on Another Site
+
+Standalone bundle:
+
+* `cul-menu.bundle.js` (IIFE, for `<script>` tags)
+* `cul-menu.bundle.es.js` (ES module)
+
+#### Example static HTML / IIFE usage
+
+```html
+<link rel="stylesheet" href="https://toolkit.library.columbia.edu/v5/setup.css">
+
+<nav data-cul-menu></nav>
+
+<script src="https://toolkit.library.columbia.edu/v5/bundles/cul-menu.bundle.js"></script>
+<script>
+  CULMenu.initCollapse({
+    url: 'https://toolkit.library.columbia.edu/v5/assets/cul-main-menu.json'
+  });
+</script>
+```
+
+*Note: script/JSON URLs can be local or remote or mixed.*
+
+---
+
+#### ES module app usage
+
+*Installation*
+
+```bash
+npm install @columbia-libraries/cul-toolkit
+```
+
+*Import and usage*
+
+```js
+import '@columbia-libraries/cul-toolkit/styles';
+import '@columbia-libraries/cul-toolkit/setup';
+
+import { makeCULmenu } from '@columbia-libraries/cul-toolkit';
+
+const MENU_URL =
+  import.meta.env.VITE_CUL_MENU_URL ||
+  'https://toolkit.library.columbia.edu/v5/assets/cul-main-menu.json';
+
+makeCULmenu(MENU_URL);
+```
+
+*Framework Notes*
+
+	makeCULmenu(MENU_URL) manipulates DOM elements with [data-cul-menu].
+	It must be called after the elements exist in the DOM:
+
+	- Vue: call after app.mount() or inside onMounted() / nextTick().
+	- React: call inside useEffect(() => { ... }, []).
+
+*Vue note:*
+```js
+import { createApp, nextTick } from 'vue';
+import App from './App.vue';
+import { makeCULmenu } from '@columbia-libraries/cul-toolkit';
+
+const app = createApp(App);
+
+// for after app is mounted:
+app.mount('#app');
+nextTick(() => {
+  makeCULmenu(MENU_URL);
+});
+
+// or for inside a component:
+onMounted(() => {
+  makeCULmenu(MENU_URL);
+});
+```
+
+*React/other frameworks:*
+
+	Call after the component that contains [data-my-menu] has mounted.
+
+*Markup requirement*
+
+	Must include target element: <nav data-my-menu></nav>
+
+--- 
+
+#### Available Globals
+
+- CULMenu.initCollapse({ url });
+- CULMenu.initNavbar({ selector, url });
+
+---
+
+### Build Output (npm package)
+
+```bash
+dist/
+├── assets/
+│   ├── columbia_crown_logo-square-135x135.svg
+│   ├── cul-main-menu.json
+│   ├── cul-text-logo.svg
+│   ├── favicon.ico
+│   ├── main.css
+│   └── main.js
+├── bundles/
+│   ├── cul-menu.bundle.es.js
+│   ├── cul-menu.bundle.es.js.map
+│   ├── cul-menu.bundle.js
+│   └── cul-menu.bundle.js.map
+├── js/
+│   ├── quicksearch.js
+│   └── typeahead-0.11.1.bundle.min.js
+├── setup.css
+└── setup.js
+```
+
+---
+
+

package/dist/assets/cul-main-menu.json

@@ -0,0 +1,234 @@
+{
+  "Services & Tools": [
+    {
+      "href": "https://library.columbia.edu/services.html",
+      "value": "Services & Tools"
+    },
+    {
+      "href": "https://library.columbia.edu/using-libraries/alumni.html",
+      "value": "For Alumni"
+    },
+    {
+      "href": "https://library.columbia.edu/services/faculty.html",
+      "value": "For Faculty"
+    },
+    {
+      "href": "https://library.columbia.edu/services.html#audience=student",
+      "value": "For Students"
+    },
+    {
+      "href": "https://library.columbia.edu/using-libraries/visitors.html",
+      "value": "For Visitors"
+    }
+  ],
+  "Libraries": [
+    {
+      "href": "https://library.columbia.edu/libraries.html",
+      "value": "Libraries & Affiliates"
+    },
+    {
+      "href": "https://library.columbia.edu/libraries/avery.html",
+      "value": "Avery Architectural & Fine Arts Library"
+    },
+    {
+      "href": "https://library.columbia.edu/libraries/burke.html",
+      "value": "Burke Library at Union Theological Seminary"
+    },
+    {
+      "href": "https://library.columbia.edu/libraries/business.html",
+      "value": "Business & Economics Library in Uris"
+    },
+    {
+      "href": "https://library.columbia.edu/libraries/business-manhattanville.html",
+      "value": "Business Library at Manhattanville"
+    },
+    {
+      "href": "https://library.columbia.edu/libraries/butler.html",
+      "value": "Butler Library"
+    },
+    {
+      "href": "https://library.columbia.edu/libraries/eastasian.html",
+      "value": "C.V. Starr East Asian Library"
+    },
+    {
+      "href": "https://library.columbia.edu/libraries/music.html",
+      "value": "Gabe M. Wiener Music & Arts Library"
+    },
+    {
+      "href": "https://library.cumc.columbia.edu/",
+      "value": "Health Sciences Library"
+    },
+    {
+      "href": "https://library.columbia.edu/libraries/journalism.html",
+      "value": "Journalism Library"
+    },
+    {
+      "href": "https://library.columbia.edu/libraries/lehman.html",
+      "value": "Lehman Social Sciences Library"
+    },
+    {
+      "href": "http://www.law.columbia.edu/library/",
+      "value": "Li Lu Law Library"
+    },
+    {
+      "href": "https://library.columbia.edu/libraries/math.html",
+      "value": "Mathematics Library"
+    },
+    {
+      "href": "https://library.columbia.edu/libraries/rbml.html",
+      "value": "Rare Book & Manuscript Library"
+    },
+    {
+      "href": "https://library.columbia.edu/libraries/science-engineering.html",
+      "value": "Science & Engineering Library"
+    },
+    {
+      "href": "https://library.columbia.edu/libraries/social-work.html",
+      "value": "Social Work Library"
+    }
+  ],
+  "Collections": [
+    {
+      "href": "https://library.columbia.edu/collections.html",
+      "value": "About Our Collections"
+    },
+    {
+      "href": "https://academiccommons.columbia.edu/",
+      "value": "Academic Commons"
+    },
+    {
+      "href": "https://library.columbia.edu/collections/archives-portal.html",
+      "value": "Archival Collections"
+    },
+    {
+      "href": "https://resolver.library.columbia.edu/clio",
+      "value": "CLIO: Columbia Libraries Catalog"
+    },
+    {
+      "href": "https://library.columbia.edu/about/policies/collection-development.html",
+      "value": "Collection Development"
+    },
+    {
+      "href": "https://dlc.library.columbia.edu",
+      "value": "Digital Collections"
+    },
+    {
+      "href": "https://library.columbia.edu/collections/eresources.html",
+      "value": "E-Resources"
+    },
+    {
+      "href": "https://resolver.library.columbia.edu/lweb0004",
+      "value": "Recommend a Title for Purchase"
+    },
+    {
+      "href": "https://library.columbia.edu/about/policies/collection-development/repatriation-return.html",
+      "value": "Repatriation"
+    },
+    {
+      "href": "https://library.columbia.edu/about/staff/subject-specialists-by-subject.html",
+      "value": "Subject Specialists"
+    }
+  ],
+  "Using the Libraries": [
+    {
+      "href": "https://library.columbia.edu/using-libraries.html",
+      "value": "Using the Libraries"
+    },
+    {
+      "href": "https://library.columbia.edu/using-libraries/access-privileges.html",
+      "value": "Access Privileges"
+    },
+    {
+      "href": "https://library.columbia.edu/using-libraries/disability.html",
+      "value": "Accessibility"
+    },
+    {
+      "href": "https://library.columbia.edu/using-libraries/borrowing.html",
+      "value": "Borrow, Request, Renew"
+    },
+    {
+      "href": "https://library.columbia.edu/services/reserves.html",
+      "value": "Course Reserves"
+    },
+    {
+      "href": "https://hours.library.columbia.edu/",
+      "value": "Hours"
+    },
+    {
+      "href": "https://library.columbia.edu/using-libraries/printing.html",
+      "value": "Print, Scan, Digitize"
+    }
+  ],
+  "Research & Teaching": [
+    {
+      "href": "https://library.columbia.edu/research-teaching.html",
+      "value": "Research & Teaching"
+    },
+    {
+      "href": "https://library.columbia.edu/research-teaching/copyright.html",
+      "value": "Copyright Information"
+    },
+    {
+      "href": "https://library.columbia.edu/research-teaching/getting-started.html",
+      "value": "Getting Started with the Libraries"
+    },
+    {
+      "href": "https://library.columbia.edu/research-teaching/global.html",
+      "value": "Global Studies"
+    },
+    {
+      "href": "https://library.columbia.edu/research-teaching/open-scholarship.html",
+      "value": "Open Scholarship Services"
+    },
+    {
+      "href": "https://library.columbia.edu/services/research-data-services.html",
+      "value": "Research Data Services"
+    },
+    {
+      "href": "https://library.columbia.edu/services/subject-guides.html",
+      "value": "Subject & Course Guides"
+    },
+    {
+      "href": "https://library.columbia.edu/research-teaching/workshops.html",
+      "value": "Workshops & Training"
+    }
+  ],
+  "About": [
+    {
+      "href": "https://library.columbia.edu/about.html",
+      "value": "About the Libraries"
+    },
+    {
+      "href": "https://library.columbia.edu/about/jobs-internships.html",
+      "value": "Jobs & Internships"
+    },
+    {
+      "href": "https://library.columbia.edu/about/news/alert.html",
+      "value": "Library Status Updates"
+    },
+    {
+      "href": "https://library.columbia.edu/about/news.html",
+      "value": "News"
+    },
+    {
+      "href": "https://library.columbia.edu/about/values.html",
+      "value": "Our Values & Commitment in Action"
+    },
+        {
+      "href": "https://library.columbia.edu/about/policies.html",
+      "value": "Policies"
+    },
+    {
+      "href": "https://library.columbia.edu/about/staff.html",
+      "value": "Staff"
+    },
+    {
+      "href": "https://strategicdirections.library.columbia.edu/",
+      "value": "Strategic Directions"
+    },
+    {
+      "href": "https://library.columbia.edu/about/student_advisory_committee.html",
+      "value": "Student Library Advisory Committee"
+    }
+  ]
+}