@cavuno/board 1.37.0 → 1.39.0

package/dist/suggest.mjs

@@ -0,0 +1,144 @@
+// src/suggest/index.ts
+var DEFAULT_MIN_CHARS = 2;
+var DEFAULT_DEBOUNCE_MS = 250;
+function isAbortError(error) {
+  return typeof DOMException !== "undefined" && error instanceof DOMException && error.name === "AbortError" || error instanceof Error && error.name === "AbortError";
+}
+function applyExclusions(items, excluded) {
+  if (excluded.size === 0) return items.slice();
+  return items.filter(
+    (item) => !(item.type === "company" && excluded.has(item.slug.toLowerCase()))
+  );
+}
+function createSuggestController(board, options) {
+  const minChars = options?.minChars ?? DEFAULT_MIN_CHARS;
+  const debounceMs = options?.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+  const limit = options?.limit;
+  let disposed = false;
+  let state = {
+    query: "",
+    items: [],
+    status: "idle",
+    error: null
+  };
+  let rawItems = [];
+  let excluded = /* @__PURE__ */ new Set();
+  let sequence = 0;
+  let timer = null;
+  let abortController = null;
+  const listeners = /* @__PURE__ */ new Set();
+  function notify() {
+    for (const listener of listeners) listener();
+  }
+  function setState(next) {
+    state = next;
+    notify();
+  }
+  function cancelTimer() {
+    if (timer !== null) {
+      globalThis.clearTimeout(timer);
+      timer = null;
+    }
+  }
+  function abortInFlight() {
+    if (abortController) {
+      abortController.abort();
+      abortController = null;
+    }
+  }
+  function runRequest(query) {
+    const seq = ++sequence;
+    abortInFlight();
+    const controller = new AbortController();
+    abortController = controller;
+    const suggestQuery = { q: query };
+    if (limit !== void 0) suggestQuery.limit = limit;
+    void board.search.suggest(suggestQuery, { signal: controller.signal }).then((result) => {
+      if (disposed || seq !== sequence) return;
+      abortController = null;
+      rawItems = result.items;
+      setState({
+        query: state.query,
+        items: applyExclusions(rawItems, excluded),
+        status: "ready",
+        error: null
+      });
+    }).catch((error) => {
+      if (disposed || seq !== sequence) return;
+      if (isAbortError(error)) return;
+      abortController = null;
+      setState({
+        query: state.query,
+        items: state.items,
+        status: "error",
+        error
+      });
+    });
+  }
+  return {
+    setQuery(query) {
+      if (disposed) return;
+      const trimmed = query.trim();
+      cancelTimer();
+      if (trimmed.length < minChars) {
+        sequence += 1;
+        abortInFlight();
+        rawItems = [];
+        setState({
+          query,
+          items: [],
+          status: "idle",
+          error: null
+        });
+        return;
+      }
+      sequence += 1;
+      abortInFlight();
+      setState({
+        query,
+        items: state.items,
+        status: "loading",
+        error: null
+      });
+      timer = globalThis.setTimeout(() => {
+        timer = null;
+        if (disposed) return;
+        runRequest(trimmed);
+      }, debounceMs);
+    },
+    setExcludedCompanySlugs(slugs) {
+      if (disposed) return;
+      excluded = new Set(
+        slugs.map((s) => s.trim().toLowerCase()).filter(Boolean)
+      );
+      setState({
+        query: state.query,
+        items: applyExclusions(rawItems, excluded),
+        status: state.status,
+        error: state.error
+      });
+    },
+    getState() {
+      return state;
+    },
+    subscribe(listener) {
+      if (disposed) return () => {
+      };
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      cancelTimer();
+      abortInFlight();
+      sequence += 1;
+      listeners.clear();
+    }
+  };
+}
+export {
+  createSuggestController
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cavuno/board",
-  "version": "1.37.0",
+  "version": "1.39.0",
   "description": "Typed isomorphic client for the Cavuno Board API",
   "license": "MIT",
   "type": "commonjs",
@@ -50,6 +50,16 @@
         "default": "./dist/filters.js"
       }
     },
+    "./suggest": {
+      "import": {
+        "types": "./dist/suggest.d.mts",
+        "default": "./dist/suggest.mjs"
+      },
+      "require": {
+        "types": "./dist/suggest.d.ts",
+        "default": "./dist/suggest.js"
+      }
+    },
     "./theme": {
       "import": {
         "types": "./dist/theme.d.mts",

package/skills/cavuno-board-filters/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cavuno-board-filters
-description: The canonical listing-filter vocabulary and URL search-param parsing with @cavuno/board/filters — remote/employment/seniority/sort sets, localized seniority labels, and parseListingFilters for jobs-listing routes. Use when building listing pages, filter sidebars, sort dropdowns, or validating listing URL params.
+description: The canonical listing-filter vocabulary and URL search-param parsing with @cavuno/board/filters — remote/employment/seniority/company/sort sets, localized seniority labels, and parseListingFilters for jobs-listing routes. Use when building listing pages, filter sidebars, sort dropdowns, or validating listing URL params.
 ---
 
 # Filters: vocabulary + URL parsing
@@ -21,6 +21,7 @@ never throws).
 - Turning values into card display text — `cavuno-board-format`.
 - Search QUERIES (`jobs.search` bodies) — this module is about the listing
   URL contract, not the search POST body.
+- Search-dropdown typeahead — `cavuno-board-suggest`.
 
 ## Parse listing URLs
 
@@ -28,19 +29,25 @@ never throws).
 import { parseListingFilters, DEFAULT_SORT } from '@cavuno/board/filters';
 
 const filters = parseListingFilters(rawSearchParams);
-// { q?, remoteOption?, employmentType?, seniority?: Seniority[], sort? }
+// { q?, remoteOption?, employmentType?, seniority?: Seniority[], company?: string[], sort? }
 
 const page = await board.jobs.list({
   limit: 20,
   seniority: filters.seniority,
+  companySlug: filters.company,
   remoteOption: filters.remoteOption ? [filters.remoteOption] : undefined,
   employmentType: filters.employmentType ? [filters.employmentType] : undefined,
 });
 ```
 
 Unknown values are dropped silently (public URLs, never throw). Seniority
-accepts repeated params or a comma-string and normalizes with the hosted
-rules: trim, lowercase, dedupe, keep order.
+and `company` accept repeated params or a comma-string and normalize with
+the hosted rules: trim, lowercase, dedupe, keep order. `company` is an open
+value set (public slugs) capped at 10 (wire max; first 10 kept).
+
+**Slugs are the URL identity.** Map `filters.company` to the wire as
+`companySlug` (`jobs.list` query / `jobs.search` filters). The API accepts
+slugs directly — never resolve slug→id client-side.
 
 ## Render the filter UI from the vocabulary
 

package/skills/cavuno-board-jobs/SKILL.md

@@ -35,7 +35,7 @@ for (const card of page.data) {
 
 ### Filters and pagination
 
-`JobsListQuery` supports `limit` (1–100), `offset` (takes precedence over `cursor`), `cursor`, and filters: `companyId`, `remoteOption`, `employmentType`, `seniority` (single or repeated → OR-matched), `location` + `radius` (km), `category`, `skill`. Paginate by passing back `nextCursor`, or use numbered pages with `offset`:
+`JobsListQuery` supports `limit` (1–100), `offset` (takes precedence over `cursor`), `cursor`, and filters: `companyId`, `companySlug`, `remoteOption`, `employmentType`, `seniority` (single or repeated → OR-matched), `location` + `radius` (km), `category`, `skill`. Paginate by passing back `nextCursor`, or use numbered pages with `offset`:
 
 ```ts snippet
 const p1 = await board.jobs.list({ limit: 20 });
@@ -46,9 +46,24 @@ const p2 = p1.nextCursor
 const page3 = await board.jobs.list({ limit: 20, offset: 40 });
 ```
 
+### Company filter via public slug
+
+`companySlug` is the public URL identity (what listing URLs carry). Prefer it
+over `companyId` in frontends — the API resolves slugs server-side. Unknown
+slugs are **ignored** (they contribute no matches, not an error); an entirely
+unknown set yields an empty result list with `count: 0`. Combined with
+`companyId` as a union when both are set. Cap is 10 values.
+
+```ts snippet
+const page = await board.jobs.list({
+  limit: 20,
+  companySlug: ['acme', 'globex'],
+});
+```
+
 ## Search
 
-`jobs.search` posts a `JobsSearchBody` (free-text `query` + structured `filters`) and returns a `JobCardSearchEnvelope`:
+`jobs.search` posts a `JobsSearchBody` (free-text `query` + structured `filters`) and returns a `JobCardSearchEnvelope`. The same `companySlug` rule applies under `filters`:
 
 ```ts snippet
 const results = await board.jobs.search({
@@ -56,6 +71,7 @@ const results = await board.jobs.search({
   filters: {
     seniority: ['senior'],
     remoteOption: ['remote'],
+    companySlug: ['acme'],
     publishedAt: { gte: '2026-01-01T00:00:00Z' },
   },
   limit: 20,

package/skills/cavuno-board-suggest/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: cavuno-board-suggest
+description: Federated keyword search suggestions with the @cavuno/board SDK — board.search.suggest for companies + taxonomy terms in one server-ranked list, and the headless createSuggestController under @cavuno/board/suggest (debounce, abort, stale-drop). Use when building a search dropdown, typeahead, or autocomplete that mirrors the hosted board.
+---
+
+# Search suggest: dropdown typeahead
+
+`board.search.suggest` returns ONE interleaved, server-ordered list of
+company and taxonomy-term suggestions for a keyword — the hosted search
+dropdown contract. `@cavuno/board/suggest` wraps that call in a headless
+controller so debounce / abort / stale-drop ship with the SDK and patch via
+npm update.
+
+## When to use
+
+- The global search input's suggestion dropdown.
+- Any typeahead that should offer companies and category/skill terms
+  together, ranked the way the hosted board ranks them.
+
+## When not to use
+
+- Location autocomplete — `board.taxonomy.places.list({ q })`.
+- Taxonomy-only option lists for filter sidebars —
+  `board.taxonomy.categories/skills/suggestions.list`.
+- Job results themselves — `board.jobs.list` / `board.jobs.search`.
+
+## Call the endpoint directly
+
+```ts snippet
+const { items, query } = await board.search.suggest({ q: 'acme', limit: 10 });
+// items is server-ranked — do NOT re-sort.
+for (const item of items) {
+  if (item.type === 'company') {
+    item.slug; // public company URL slug
+    item.name;
+    item.jobCount;
+  } else {
+    // item.type === 'term'
+    item.termType; // 'category' | 'skill'
+    item.displayName;
+    item.canonicalSlug; // for links
+    item.sourceSlug; // for job filters
+  }
+}
+```
+
+Queries under two characters return an empty `items` array. `limit` is
+1–25 (default 25). Order is the contract.
+
+## Prefer the headless controller for UI
+
+The controller owns debounce (default 250ms), min-chars (default 2),
+in-flight abort, and stale-drop. Compatible with `useSyncExternalStore`.
+
+```ts snippet
+import { createSuggestController } from '@cavuno/board/suggest';
+
+const suggest = createSuggestController(board, { limit: 10 });
+const unsub = suggest.subscribe(() => {
+  const { items, status, query } = suggest.getState();
+  // render dropdown; previous items are retained while status === 'loading'
+});
+suggest.setQuery(inputValue);
+// Hide the currently-applied company filter from the list:
+suggest.setExcludedCompanySlugs(appliedCompanySlugs);
+// teardown:
+unsub();
+suggest.dispose();
+```
+
+`setExcludedCompanySlugs` is the ONE permitted view-level filter (company
+items only, re-filters current items synchronously — no new request). Never
+reshape or re-sort the rest of the response.
+
+## Wire a company pick into the listing
+
+Company slugs are the URL identity. Map them onto the jobs surface as
+`companySlug` — never resolve slug→id client-side:
+
+```ts snippet
+import { parseListingFilters } from '@cavuno/board/filters';
+
+const filters = parseListingFilters(rawSearchParams);
+// filters.company is string[] of public slugs
+
+const page = await board.jobs.list({
+  limit: 20,
+  companySlug: filters.company,
+});
+```
+
+Unknown slugs are dropped server-side (not an error). If the entire company
+filter resolves to no known companies, the listing is empty (`count: 0`).
+Combined with `companyId` as a union when both are set.
+
+## Anti-patterns
+
+```ts no-check
+// NEVER re-sort server-ranked items:
+items.sort((a, b) => a.name.localeCompare(b.name));
+// NEVER resolve company slug → id on the client:
+const id = await lookupCompanyId(item.slug);
+board.jobs.list({ companyId: [id] });
+// NEVER hand-roll debounce/abort — use the controller so patches ship via npm.
+```
+
+## Out of scope — do not invent exports
+
+No React components, no dropdown UI, no keyboard navigation — this package
+is the data + controller layer. Location suggest stays on `taxonomy.places`.
+
+## Verify
+
+- [ ] Typing under 2 characters shows no suggestions and no network call
+      from the controller.
+- [ ] Fast typing cancels the previous request; only the final query's
+      results render.
+- [ ] Selecting a company writes its public slug into the URL and the
+      listing request uses `companySlug`, not a client-resolved id.

package/skills/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.37.0",
+  "version": "1.39.0",
   "skills": [
     {
       "name": "cavuno-board-account",
@@ -52,7 +52,7 @@
     },
     {
       "name": "cavuno-board-filters",
-      "description": "The canonical listing-filter vocabulary and URL search-param parsing with @cavuno/board/filters — remote/employment/seniority/sort sets, localized seniority labels, and parseListingFilters for jobs-listing routes. Use when building listing pages, filter sidebars, sort dropdowns, or validating listing URL params.",
+      "description": "The canonical listing-filter vocabulary and URL search-param parsing with @cavuno/board/filters — remote/employment/seniority/company/sort sets, localized seniority labels, and parseListingFilters for jobs-listing routes. Use when building listing pages, filter sidebars, sort dropdowns, or validating listing URL params.",
       "path": "skills/cavuno-board-filters/SKILL.md",
       "framework": null,
       "category": "core"
@@ -148,6 +148,13 @@
       "framework": null,
       "category": "core"
     },
+    {
+      "name": "cavuno-board-suggest",
+      "description": "Federated keyword search suggestions with the @cavuno/board SDK — board.search.suggest for companies + taxonomy terms in one server-ranked list, and the headless createSuggestController under @cavuno/board/suggest (debounce, abort, stale-drop). Use when building a search dropdown, typeahead, or autocomplete that mirrors the hosted board.",
+      "path": "skills/cavuno-board-suggest/SKILL.md",
+      "framework": null,
+      "category": "core"
+    },
     {
       "name": "cavuno-board-tanstack-start",
       "description": "TanStack-Start-on-Cloudflare-Workers reference wiring for a headless Cavuno board — SSR loaders calling @cavuno/board server-side, the session held in an __Host- httpOnly cookie owned by the app, a single-flight refresh helper, and FetchOptions cache passthrough on Workers.",