chore(docs): update readme.md

smarcet · smarcet · commit 086fafc4ae59 · 2026-03-11T16:01:15.000-03:00
chore(build): update build to use yarn
fix(template): change search placeholder
diff --git a/.claude/rules/openstack-search-widget-conventions.md b/.claude/rules/openstack-search-widget-conventions.md
@@ -0,0 +1,54 @@
+# Coding Conventions
+
+## AMD Modules
+
+All JS files use RequireJS AMD format. Never use CommonJS `require()` or ES modules.
+
+```javascript
+// Correct — AMD define with dependency array
+define(['jquery', 'ractive', 'rv!templates/template'], function ($, Ractive, mainTemplate) {
+    'use strict';
+    // ...
+});
+```
+
+Module paths are mapped in `config.js`. When adding a dependency:
+1. `npm install --save <package>`
+2. Add path mapping to `config.js`
+3. Add to `define([...])` dependency array
+
+## jQuery noConflict
+
+jQuery runs in `$.noConflict()` mode. **IMPORTANT:** Always use the `$` variable from the AMD module parameter, never assume a global `$` or `jQuery`.
+
+```javascript
+// Correct — $ comes from the AMD define callback
+define(['jquery'], function ($) {
+    $.ajax({ ... });
+    $('.ossw-search-bar', el).show();
+});
+```
+
+## Ractive Templates
+
+- Templates use Ractive mustache syntax (`{{variable}}`, `{{{unescaped}}}`, `{{#if}}`, `{{#each}}`)
+- Located in `templates/` directory
+- Loaded via RequireJS `rv!` plugin: `'rv!templates/template'`
+- Events bound with `on-click="eventName"` and `on-keyup="eventName"`
+
+## CSS
+
+- All widget classes use the `ossw-` prefix (OpenStack Search Widget) to avoid conflicts with host page styles
+- CSS is loaded as a text module and injected into `<head>` at runtime — no external stylesheet link needed
+- Widget uses `z-index` values in the 99999991–99999997 range for the popup overlay
+
+## API Integration
+
+- AJAX calls use `$.ajax()` with `dataType: "json"`
+- Suggestions use a debounce pattern: 500ms `setTimeout` + abort previous XHR
+- Search results prefer `meta_title`/`meta_description` over `title`/`content`
+- Result detail text is truncated to 100 characters (`MAX_DETAIL_LEN`)
+
+## Build Output
+
+`embed.min.js` is committed to the repo. After any JS or template change, rebuild with `make js` and commit the updated `embed.min.js`.
diff --git a/.claude/rules/openstack-search-widget-project.md b/.claude/rules/openstack-search-widget-project.md
@@ -0,0 +1,77 @@
+# Project: OpenStack Search Bar Widget
+
+**Last Updated:** 2026-03-11
+
+## Overview
+
+Embedded search bar widget for OpenStack sites. Provides search with autocomplete suggestions and paginated results via a popup overlay. Designed to be embedded on any page via a single `<div>` + script tag.
+
+## Technology Stack
+
+- **Language:** JavaScript (ES5, no transpilation)
+- **Module System:** RequireJS (AMD) with `almond` for production builds
+- **UI Framework:** Ractive.js 0.10.x (reactive templates with mustache syntax)
+- **DOM / AJAX:** jQuery 3.x (`$.noConflict()` mode — always use `$` from the AMD module, never global)
+- **Build Tool:** RequireJS Optimizer (`r.js`) via Makefile
+- **Icons:** Font Awesome 4.7 (loaded externally by the embedding page)
+- **Tests:** None configured
+
+## Directory Structure
+
+```
+├── app/app.js          # Main widget logic (search, suggestions, pagination)
+├── config.js           # RequireJS path configuration
+├── embed.js            # Entry point — loads jQuery + app, calls app.init()
+├── embed.build.js      # r.js optimizer build config
+├── embed.min.js        # Built/minified output (committed)
+├── css/widget-styles.css
+├── templates/template.html  # Ractive template (mustache syntax)
+├── example/index.html       # Test page for the widget
+└── Makefile
+```
+
+## Key Files
+
+- **Entry Point:** `embed.js` → requires `app/app.js` → calls `app.init()`
+- **Build Config:** `embed.build.js` (r.js optimizer settings)
+- **RequireJS Paths:** `config.js` (maps module names to `node_modules/` paths)
+- **Output:** `embed.min.js` (self-contained bundle with almond loader)
+
+## Development Commands
+
+| Task | Command |
+|------|---------|
+| Install deps | `make init` (or `npm install`) |
+| Build CSS | `make css` |
+| Build JS | `make js` |
+| Build all | `make` |
+| Test locally | Open `example/index.html` in a browser after building |
+
+## Architecture
+
+### Embedding
+
+Host pages add a `<div class="openstack-search-bar">` with data attributes and load `embed.min.js`:
+
+```html
+<div class="openstack-search-bar" data-baseUrl="search.openstack.org" data-context="www-openstack"></div>
+```
+
+- `data-baseUrl` — API host (default: `search.openstack.org`)
+- `data-context` — search context/scope (default: `www-openstack`)
+
+### API Endpoints
+
+All requests go to `https://{baseUrl}/api/public/v1/`:
+
+| Endpoint | Purpose |
+|----------|---------|
+| `search/{context}/{term}?page=N&page_size=N` | Full search with pagination |
+| `suggestions/{context}/{term}` | Autocomplete suggestions |
+
+### Widget Lifecycle
+
+1. `embed.min.js` loads → RequireJS resolves AMD modules
+2. `app.init()` finds all `.openstack-search-bar` elements
+3. Each element gets its own Ractive instance with search/suggestion/pagination state
+4. CSS is injected into `<head>` at runtime
diff --git a/.nvmrc b/.nvmrc
@@ -0,0 +1 @@
+20
diff --git a/Makefile b/Makefile
@@ -1,7 +1,7 @@
 all: css js
 
 init:
-	npm install --save almond requirejs requirejs-text jquery ractive rv
+	yarn install
 
 css:
 	node_modules/requirejs/bin/r.js -o cssIn=css/widget-styles.css out=css/widget-styles_embed.css
diff --git a/README.md b/README.md
@@ -2,13 +2,19 @@
 
 Search Bar embedded widget using [RequireJS](http://requirejs.org) and [Ractive.js](http://ractivejs.org).
 
-## Building the widget
+## Prerequisites
+
+- [nvm](https://github.com/nvm-sh/nvm) (recommended) or Node.js 20+
+- [Yarn](https://classic.yarnpkg.com/)
 
-Assuming RequireJS is already installed:
+## Building the widget
 
 ```console
+$ nvm use
 $ make init
 $ make
 ```
 
-Now you can test ``embed.min.js`` with ``examples/index.html``
+`make init` runs `yarn install` to fetch dependencies. `make` builds both the CSS and the minified JS bundle (`embed.min.js`).
+
+You can test the result by opening `example/index.html` in a browser.
diff --git a/embed.min.js b/embed.min.js
diff --git a/package-lock.json b/package-lock.json
diff --git a/templates/template.html b/templates/template.html
@@ -1,6 +1,6 @@
 <div class="ossw-search-wrapper">
     <div class="ossw-search-bar-wrapper">
-        <input value="{{term}}" on-keyup="search" type="text" id="search-bar-input" placeholder="Search OpenStack" />
+        <input value="{{term}}" on-keyup="search" type="text" id="search-bar-input" placeholder="Search this site" />
         <i class="fa fa-times ossw-search-bar-close" on-click="clear"></i>
     </div>
     <div class="ossw-search-suggestions-wrapper">
diff --git a/yarn.lock b/yarn.lock
@@ -0,0 +1,45 @@
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+# yarn lockfile v1
+
+
+almond@^0.3.3:
+  version "0.3.3"
+  resolved "https://registry.npmjs.org/almond/-/almond-0.3.3.tgz#a0e7c95ac7624d6417b4494b1e68bff693168a20"
+  integrity sha512-Eh5QhyxrKnTI0OuGpwTRvzRrnu1NF3F2kbQJRwpXj/uMy0uycwqw2/RhdDrD1cBTD1JFFHFrxGIU8HQztowR0g==
+
+jquery@^3.3.1:
+  version "3.7.1"
+  resolved "https://registry.npmjs.org/jquery/-/jquery-3.7.1.tgz#083ef98927c9a6a74d05a6af02806566d16274de"
+  integrity sha512-m4avr8yL8kmFN8psrbFFFmB/If14iN5o9nw/NgnnM+kybDJpRsAynV2BsfpTYrTRysYUdADVD7CkUUizgkpLfg==
+
+ractive@^0.10.9:
+  version "0.10.14"
+  resolved "https://registry.npmjs.org/ractive/-/ractive-0.10.14.tgz#0d3c2d2c8e4c686970f94127f29c2fef6f9de37c"
+  integrity sha512-56mYF41urs/v0SUBpLIa1GyZrnugRBB3rkZlKHnPxcbPDK7mFIPSaA2fKn+4DKsjmMkSbmmXqaHrzZdx9keZsA==
+
+ractive@^0.9.11:
+  version "0.9.14"
+  resolved "https://registry.npmjs.org/ractive/-/ractive-0.9.14.tgz#aa0834185bfaa57bfeb12ab9f842c1904fe25a6d"
+  integrity sha512-qqOkqPho+X84N2xZx0HcxaGCSBnBzpv3Y7NzQxqj5hsAfnq7HAaHq+6w1PQhyo8tCZj+BijbKP6t1uJWmgBnLQ==
+
+requirejs-text@^2.0.15:
+  version "2.0.16"
+  resolved "https://registry.npmjs.org/requirejs-text/-/requirejs-text-2.0.16.tgz#b6f3e20689aa998e36641bc4f8bd11b7964ac872"
+  integrity sha512-XrzjeTb1pwzIWmkz8qnUiM20gENgiwB+66IciNuziwlaPAJsYQsQPSYyQ1kD4tGKGZxTisIfDbOHk02DpI/76Q==
+
+requirejs@^2.3.6:
+  version "2.3.8"
+  resolved "https://registry.npmjs.org/requirejs/-/requirejs-2.3.8.tgz#bca0614b618ab2122462597e44878db7558bbba3"
+  integrity sha512-7/cTSLOdYkNBNJcDMWf+luFvMriVm7eYxp4BcFCsAX0wF421Vyce5SXP17c+Jd5otXKGNehIonFlyQXSowL6Mw==
+
+rv@^0.1.8:
+  version "0.1.8"
+  resolved "https://registry.npmjs.org/rv/-/rv-0.1.8.tgz#1d5f0203a0d3a59158bd2de8bd8a59efc9cb7541"
+  integrity sha512-zKF0bGUi1yHZuxtUzuFVOLTy19XeAH0g/4SQ/GkS5HRMOIJyRA69/LV45Tz6k0J48KaYQeElsQsVeotuav3Ouw==
+
+rvc@^0.5.0:
+  version "0.5.0"
+  resolved "https://registry.npmjs.org/rvc/-/rvc-0.5.0.tgz#fc3546d4f909218b08c90043304e83cecf80072e"
+  integrity sha512-6ipnueSkuW2KTGakQkpr1fO62PStz47R+gTLXq3ughAzhlqIiwyl/LJtyUcmLrcg2CPPuNrQkwKQP+TD9bDreg==
+  dependencies:
+    ractive "^0.9.11"
