hal-search 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jey Puget Gil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,214 @@
+# hal-search
+
+A zero-dependency TypeScript library for querying and displaying articles from the [HAL Open Archive](https://hal.science/) API.
+
+---
+
+## Goal
+
+**hal-search** lets you embed a live, paginated list of academic publications from the HAL API into any web page with a single class instantiation. It handles:
+
+- Building the correct HAL API query from a user ID or free-text query
+- Fetching results at a configurable level of detail (minimal → full)
+- Rendering styled article cards with pagination
+- Exposing callbacks for results and errors
+
+---
+
+## Installation
+
+```bash
+# from npm (once published)
+npm install hal-search
+
+# or use the built files directly
+dist/hal-search.es.js   # ES module
+dist/hal-search.umd.js  # UMD (browser global: window.HalSearch)
+```
+
+---
+
+## Usage
+
+### Basic example
+
+```html
+<div id="publications"></div>
+
+<script type="module">
+  import { HalSearch } from './dist/hal-search.es.js';
+
+  const hs = new HalSearch({
+    container: '#publications',
+    lvl: 1,
+    rows: 10,
+    onResults: (res) => console.log(`${res.response.numFound} results`),
+    onError:   (err) => console.error(err.message),
+  });
+
+  hs.search({ uid: 'authIdHal_s:jdupont' });
+</script>
+```
+
+### Constructor options
+
+| Option         | Type                              | Default | Description |
+|----------------|-----------------------------------|---------|-------------|
+| `container`    | `HTMLElement \| string`           | —       | Target DOM element or CSS selector (optional if output='svg') |
+| `lvl`          | `0 \| 1 \| 2 \| 3`              | `1`     | Level of detail (see below) |
+| `rows`         | `number`                          | `10`    | Results per page |
+| `apiBase`      | `string`                          | HAL URL | Override the API base URL |
+| `injectStyles` | `boolean`                         | `true`  | Auto-inject the default stylesheet |
+| `onResults`    | `(res: HalApiResponse) => void`   | —       | Called on every successful fetch |
+| `onError`      | `(err: Error) => void`            | —       | Called when the fetch fails |
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `search({ uid, rows?, start? })` | Start a new search. Returns `Promise<SVGSVGElement>` if headless SVG mode. |
+| `setLevel(lvl)` | Change detail level and re-fetch. Returns `Promise<SVGSVGElement>` if headless SVG mode. |
+| `goToPage(n)` | Jump to page `n` (1-based). Returns `Promise<SVGSVGElement>` if headless SVG mode. |
+| `nextPage()` | Go to the next page. Returns `Promise<SVGSVGElement>` if headless SVG mode. |
+| `prevPage()` | Go to the previous page. Returns `Promise<SVGSVGElement>` if headless SVG mode. |
+| `destroy()` | Clear the container (if one was provided) |
+
+### Headless SVG generation
+
+You can generate a standalone SVG without attaching it to the DOM by omitting the `container` option and setting `output: 'svg'`. The `search()` method (and pagination methods) will resolve with the SVG element.
+
+```js
+const hs = new HalSearch({
+  output: 'svg',
+  lvl: 2,
+  rows: 5,
+});
+
+const svgElement = await hs.search({ uid: 'authIdHal_s:jdupont' });
+document.body.appendChild(svgElement);
+```
+
+### Detail levels
+
+The `lvl` parameter controls which HAL fields are requested and how much information is shown per article.
+
+| Level | Name | Fields fetched | What is displayed |
+|-------|------|---------------|-------------------|
+| `0` | Minimal | `docid`, `label_s`, `uri_s` | Citation label + link |
+| `1` | Basic *(default)* | + `title_s`, `authFullName_s`, `publicationDate_s`, `docType_s` | Title, authors, year, document type |
+| `2` | Detailed | + `keyword_s`, `domain_s`, `openAccess_bool`, `language_s`, `conferenceTitle_s` | All of the above + tags, OA badge, conference |
+| `3` | Full | `*` (all fields) | Adds the abstract of the paper |
+
+### Theming
+
+Default styles use CSS custom properties. Override any of them on the container or globally:
+
+```css
+#publications {
+  --hal-accent:       #e63946;
+  --hal-bg-article:   #fff8f0;
+  --hal-radius:       4px;
+}
+```
+
+| Variable | Default |
+|----------|---------|
+| `--hal-accent` | `#0052cc` |
+| `--hal-accent-hover` | `#003d99` |
+| `--hal-bg` | `#ffffff` |
+| `--hal-bg-article` | `#fafafa` |
+| `--hal-border` | `#e0e0e0` |
+| `--hal-text` | `#1a1a1a` |
+| `--hal-text-muted` | `#666666` |
+| `--hal-radius` | `6px` |
+
+Disable auto-injection with `injectStyles: false` and provide your own stylesheet.
+
+### Building a query
+
+The `uid` field passed to `search()` maps directly to the `q` parameter of the HAL Solr API, so any valid Solr query works:
+
+```js
+// Free-text
+hs.search({ uid: 'machine learning' });
+
+// Author by HAL identifier
+hs.search({ uid: 'authIdHal_s:jdupont' });
+
+// By lab structure
+hs.search({ uid: 'structId_i:123456' });
+```
+
+See the [HAL API documentation](https://api.archives-ouvertes.fr/docs/search) for the full query syntax.
+
+---
+
+## Running the example
+
+```bash
+npm run example
+```
+
+This builds the library and serves the interactive demo at **http://localhost:8080/example/**. The demo lets you switch queries, levels, and page size in real time.
+
+To run the development sandbox (requires Vite):
+
+```bash
+npm run dev
+# open http://localhost:5173
+```
+
+---
+
+## Contributing
+
+### Project structure
+
+```
+src/
+  index.ts       # Public exports
+  HalSearch.ts   # Main class
+  api.ts         # URL builder + fetch logic
+  levels.ts      # Field lists per detail level
+  renderer.ts    # DOM rendering
+  styles.ts      # Default CSS
+  types.ts       # TypeScript interfaces
+example/
+  index.html     # Interactive demo
+dist/            # Built output (generated)
+```
+
+### Development setup
+
+```bash
+git clone <repo>
+cd hal-search
+npm install
+npm run dev      # live dev server at localhost:5173
+```
+
+### Building
+
+```bash
+npm run build
+```
+
+Produces:
+
+| File | Format | Use case |
+|------|--------|----------|
+| `dist/hal-search.es.js` | ES module | Bundlers, `<script type="module">` |
+| `dist/hal-search.umd.js` | UMD | `<script>` tag, CommonJS |
+| `dist/index.d.ts` | TypeScript types | TypeScript consumers |
+
+### Guidelines
+
+- **TypeScript strict mode** is enabled — all code must type-check cleanly.
+- Keep the library **zero-dependency** at runtime; dev dependencies are fine.
+- Rendering lives in `renderer.ts`, API logic in `api.ts` — keep concerns separated.
+- Test new features against both the dev sandbox (`index.html`) and the example page (`example/index.html`).
+- Follow the existing naming conventions for CSS classes (`.hal-*`).
+
+### Useful link
+
+- [HAL API documentation](https://api.archives-ouvertes.fr/docs/search)

package/dist/HalSearch.d.ts

@@ -0,0 +1,23 @@
+import { HalSearchOptions, SearchParams, DetailLevel } from './types';
+export declare class HalSearch {
+    private readonly container?;
+    private options;
+    private pagination;
+    private currentUid;
+    constructor(options: HalSearchOptions);
+    /** Start a new search, resetting to page 1. */
+    search(params: SearchParams): Promise<SVGSVGElement | void>;
+    /** Navigate to a specific page number (1-based). */
+    goToPage(page: number): Promise<SVGSVGElement | void>;
+    /** Navigate to the next page. */
+    nextPage(): Promise<SVGSVGElement | void>;
+    /** Navigate to the previous page. */
+    prevPage(): Promise<SVGSVGElement | void>;
+    /** Change the detail level and re-fetch the current results. */
+    setLevel(lvl: DetailLevel): Promise<SVGSVGElement | void>;
+    /** Clear the container and remove rendered content. */
+    destroy(): void;
+    private _fetch;
+    private _resolveContainer;
+    private _updatePagination;
+}

package/dist/api.d.ts

@@ -0,0 +1,12 @@
+import { HalApiResponse, DetailLevel } from './types';
+export declare const DEFAULT_BASE = "https://api.archives-ouvertes.fr/search/";
+/**
+ * Builds a HAL API search URL from the given parameters.
+ * Uses URLSearchParams to safely encode special characters in uid.
+ */
+export declare function buildUrl(uid: string, lvl: DetailLevel, rows: number, start: number, base?: string): string;
+/**
+ * Fetches articles from the HAL API.
+ * Throws on HTTP errors or non-zero API status codes.
+ */
+export declare function fetchArticles(uid: string, lvl: DetailLevel, rows: number, start: number, base?: string): Promise<HalApiResponse>;

package/dist/embed.d.ts

@@ -0,0 +1,21 @@
+import { DetailLevel } from './types';
+export interface EmbedOptions {
+    /** Base URL where embed.html is hosted */
+    embedBase: string;
+    /** Search query or author UID */
+    uid: string;
+    /** Detail level 0-3 */
+    lvl?: DetailLevel;
+    /** Results per page */
+    rows?: number;
+    /** Render mode: 'html' (default) for interactive cards, 'svg' for a static SVG */
+    type?: 'html' | 'svg';
+    /** iframe width (CSS value) */
+    width?: string;
+    /** iframe height (CSS value) */
+    height?: string;
+}
+/** Builds the URL for the embeddable page with query parameters. */
+export declare function buildEmbedUrl(options: EmbedOptions): string;
+/** Returns a ready-to-paste `<iframe>` HTML snippet. */
+export declare function buildEmbedSnippet(options: EmbedOptions): string;