@mframework/layer-search 0.0.1

package/README.md

@@ -0,0 +1,269 @@
+<!-- packages/search/README.md -->
+# @mframework/layer-search
+
+A modular, provider-agnostic search layer for the M Framework. It provides a unified, typed search API with pluggable adapters (Meilisearch, OpenSearch, mock adapters), lightweight bridges for UI integrations (InstantSearch / Searchkit), a small CLI for indexing/warmup, and event hooks.
+
+## Features
+
+- Plug-and-play adapters (Meilisearch, OpenSearch, Mock)
+- Fully typed integration with `@mframework/core`
+- Mock adapter for tests
+- Small CLI for indexing and warmup
+- Configuration validation and event hooks (`search:query`, `search:results`)
+
+## Installation
+
+Using npm:
+
+```bash
+npm install @mframework/layer-search
+```
+
+Using pnpm:
+
+```bash
+pnpm add @mframework/layer-search
+```
+
+## Quick Usage
+
+Register the module with an M Framework app:
+
+```ts
+import { createM FrameworkApp } from '@mframework/core'
+import searchModule from '@mframework/layer-search'
+
+const app = createM FrameworkApp({
+  config: {
+    search: {
+      defaultProvider: 'opensearch',
+      providers: {
+        opensearch: {
+          host: 'http://localhost:7700',
+          index: 'products',
+          apiKey: 'masterKey'
+        }
+      }
+    }
+  },
+  modules: [searchModule]
+})
+
+await app.start()
+
+// After app startup you can access the registered `search` adapter via the runtime
+const searchAdapter = app.context.getAdapter('search')
+if (searchAdapter) {
+  const results = await searchAdapter.search({ term: 'shoes', page: 1, pageSize: 10 })
+  console.log(results.items)
+}
+```
+
+## Adapters
+
+Adapters are intentionally provider-agnostic and may be supplied by external packages or by your application.
+The core `@mframework/layer-search` layer does not bundle provider implementations; instead provide an adapter instance at startup
+or register one at runtime so the search manager can be created.
+
+Example (external adapter package or custom implementation):
+
+```ts
+// import from an external adapter package or your own implementation
+import { createMySearchAdapter } from 'my-search-adapter-package' /* @mframework/adapter-opensearch */
+
+const adapter = createMySearchAdapter({ /* provider config */ })
+```
+
+Register the adapter either when creating the M Framework app or at runtime (both shown below).
+
+## Configuration
+
+Example `search` config in your app:
+
+```json
+{
+  "search": {
+    "defaultProvider": "opensearch",
+    "providers": {
+      "opensearch": {
+        "endpoint": "https://my-opensearch.com",
+        "index": "products"
+      }
+    }
+  }
+}
+```
+
+The module validates that `defaultProvider` and the referenced provider configuration exist, and that required fields for each adapter are present.
+
+Note: this repository includes a top-level `.env.example` with recommended variables for Search and other providers; you can manage layer credentials from your main app's `.env` file. See `../.env.example`.
+
+## UI Integrations (InstantSearch / Searchkit)
+
+This layer includes bridges that let UI code use Algolia InstantSearch or Searchkit clients without coupling the UI to a particular backend provider. Use `createInstantSearchBridge` / `createSearchkitBridge` on the client, and `createSearchkitGraphQLHandler` on the server when exposing a GraphQL endpoint for Searchkit-server.
+
+Example (client):
+
+```ts
+import { createInstantSearchBridge } from '@mframework/layer-search'
+// `manager` is the `SearchManager` instance available on the app context
+const bridge = createInstantSearchBridge(manager)
+
+const instantsearchClient = {
+  search(requests) {
+    return bridge.searchFunction({ state: requests[0].params, setResults: () => {} })
+  }
+}
+```
+
+Example (server - Express):
+
+```ts
+import express from 'express'
+import { createSearchkitGraphQLHandler } from '@mframework/layer-search'
+
+const app = express()
+app.use(express.json())
+app.post('/graphql', createSearchkitGraphQLHandler(manager))
+```
+
+These bridges map InstantSearch/Searchkit request shapes into the layer's `SearchManager` and underlying adapters so UI code doesn't need to change when you swap search providers.
+
+## Events
+
+This module emits bus events that you can listen to:
+
+```ts
+bus.on('search:query', ({ term }) => {
+  console.log('User searched for:', term)
+})
+
+bus.on('search:results', ({ term, total }) => {
+  console.log(`Search for "${term}" returned ${total} results`)
+})
+```
+
+**Registering external adapters**
+
+There are two common ways to register a search adapter so the search layer can use it:
+
+- Module-based (recommended at startup): create a small provider module that exposes the adapter via the module `adapters` property. The module registry will register the adapter before modules run.
+
+```ts
+import { createM FrameworkApp } from '@mframework/core'
+import searchModule from '@mframework/layer-search'
+import { createMySearchAdapter } from 'my-search-adapter-package' /* @mframework/adapter-opensearch */
+
+const myProviderModule = {
+  id: 'search-provider-my',
+  adapters: {
+    search: createMySearchAdapter({ /* config */ })
+  }
+}
+
+const app = createM FrameworkApp({
+  config: { /* ... */ },
+  modules: [searchModule, myProviderModule]
+})
+
+await app.start()
+```
+
+- Runtime registration: register an adapter into the core module registry at runtime. This is useful for registering adapters from other modules or dynamic initialization.
+
+```ts
+import { createM FrameworkApp } from '@mframework/core'
+import searchModule from '@mframework/layer-search'
+import { createMySearchAdapter } from 'my-search-adapter-package' /* @mframework/adapter-opensearch */
+
+const app = createM FrameworkApp({ modules: [searchModule] })
+
+// register adapter before or after `app.start()`
+app.context.modules.registerAdapter('search', createMySearchAdapter({ /* config */ }))
+
+await app.start()
+```
+
+Notes:
+
+- Many layers adopt a convention of emitting `adapter:registered` events; the search layer listens for adapter registrations and will initialize its `SearchManager` when a `search` adapter becomes available.
+- If you publish adapters, prefer a small package such as `@your-org/adapter-mysearch` that exports a `createMySearchAdapter` factory so consumers can import and register it using one of the patterns above.
+
+
+## CLI
+
+Included CLI commands:
+
+- Warmup: `meeovi-search warmup`
+- Index a JSON file: `meeovi-search index ./products.json`
+
+Environment variables supported (example for Meilisearch):
+
+- `SEARCH_PROVIDER=opensearch`
+- `MEILI_HOST=http://localhost:7700`
+- `MEILI_INDEX=products`
+- `MEILI_KEY=masterKey`
+
+Searchkit / Search provider environment variables
+
+- `SEARCHKIT_HOST` or `NUXT_PUBLIC_SEARCHKIT_HOST` — full host URL (e.g. `https://search.example.com`)
+- Alternatively compose with:
+  - `SEARCHKIT_PROTOCOL` / `NUXT_PUBLIC_SEARCHKIT_PROTOCOL` (defaults to `http`)
+  - `SEARCHKIT_HOSTNAME` / `NUXT_PUBLIC_SEARCHKIT_HOSTNAME` (e.g. `search.example.com`)
+  - `SEARCHKIT_PORT` / `NUXT_PUBLIC_SEARCHKIT_PORT` (e.g. `9200`)
+- Optional API key: `SEARCHKIT_API_KEY` or `NUXT_PUBLIC_SEARCHKIT_API_KEY`
+
+Notes:
+- Use the `NUXT_PUBLIC_` prefix for values that must be available in client-side code (public build). Keep API keys server-only when possible.
+- The plugin logs a runtime validation message on startup if search provider configuration is missing, with examples of env vars to set.
+
+Layer env conventions
+
+- All layers use the same environment lookup convention: the code checks `KEY` and falls back to `NUXT_PUBLIC_KEY` when appropriate. This lets you manage provider credentials and endpoints centrally from your main application's `.env` file.
+- Example `.env` entries in your main app to configure the Search layer:
+
+```
+SEARCHKIT_HOST=https://search.example.com
+SEARCHKIT_API_KEY=server-only-key
+# or compose:
+SEARCHKIT_PROTOCOL=https
+SEARCHKIT_HOSTNAME=search.example.com
+SEARCHKIT_PORT=9200
+```
+
+Because every layer follows this `KEY` / `NUXT_PUBLIC_KEY` pattern, you can place settings in the main app's `.env` and they will be available to the layer at runtime without editing layer files.
+
+## Testing
+
+Use the mock adapter in tests to avoid external dependencies:
+
+```ts
+import { createMockSearchAdapter } from '@mframework/layer-search'
+
+const mock = createMockSearchAdapter([{ id: '1', title: 'Test Product' }])
+const results = await mock.search({ term: 'test' })
+```
+
+## File structure
+
+Typical layout:
+
+```
+@mframework/layer-search
+├─ src/
+│  ├─ index.ts
+│  ├─ module.ts
+│  ├─ adapter/
+│  │  ├─ mock.ts
+│  │  └─ types.ts
+│  ├─ config/schema.ts
+│  ├─ events.ts
+│  └─ utils/normalizers.ts
+├─ cli.ts
+├─ package.json
+└─ README.md
+```
+
+## License
+
+MIT

package/app/components/README.md

@@ -0,0 +1,3 @@
+## Search Directory
+
+For all search visual features are found within this directory.

package/app/components/features/autocomplete.vue

@@ -0,0 +1,63 @@
+<template>
+	<div class="autocomplete">
+		<input
+			v-model="input"
+			@input="onInput"
+			@keydown.enter.prevent="onSelectFirst"
+			:placeholder="placeholder"
+			class="autocomplete-input"
+		/>
+		<ul v-if="suggestions.length" class="autocomplete-list">
+			<li v-for="(s, i) in suggestions" :key="i" @click="select(s)">
+				<div class="title">{{ s.title || s.name || s.label || s.id }}</div>
+				<div class="subtitle" v-if="s.description">{{ s.description }}</div>
+			</li>
+		</ul>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref, watch } from 'vue'
+import useSearchkit from '../../composables/useSearchkit'
+
+const props = defineProps({ placeholder: { type: String, default: 'Search...' } })
+const emits = defineEmits(['select', 'input'])
+
+const { autocomplete } = useSearchkit()
+const input = ref('')
+const suggestions = ref<any[]>([])
+let timer: any = null
+
+async function onInput() {
+	emits('input', input.value)
+	clearTimeout(timer)
+	timer = setTimeout(async () => {
+		if (!input.value || input.value.length < 1) {
+			suggestions.value = []
+			return
+		}
+		suggestions.value = await autocomplete(input.value, 6)
+	}, 180)
+}
+
+function select(item: any) {
+	emits('select', item)
+	suggestions.value = []
+}
+
+function onSelectFirst() {
+	if (suggestions.value.length) select(suggestions.value[0])
+}
+
+watch(input, (v) => {
+	if (!v) suggestions.value = []
+})
+</script>
+
+<style scoped>
+.autocomplete { position: relative; }
+.autocomplete-list { position: absolute; left: 0; right: 0; background: white; z-index: 50; list-style: none; margin: 0; padding: 0; border: 1px solid #ddd; }
+.autocomplete-list li { padding: 8px; cursor: pointer; }
+.autocomplete-list li:hover { background: #f5f5f5; }
+.autocomplete-input { width: 100%; padding: 8px; border: 1px solid #ccc; }
+</style>

package/app/components/features/searchkitSearch.vue

@@ -0,0 +1,115 @@
+<template>
+  <div class="searchkit-search">
+    <div class="controls">
+      <SearchInput v-model="query" @search="onSearch" />
+      <autocomplete @input="onInput" @select="onSelect" />
+
+      <label>
+        <select v-model="ranking" @change="onRankingChange">
+          <option value="relevance">Relevance</option>
+          <option value="newest">Newest</option>
+          <option value="popularity">Popularity</option>
+        </select>
+      </label>
+
+      <label>
+        Semantic:
+        <input type="checkbox" v-model="semanticEnabled" @change="toggleSemantic" />
+      </label>
+
+      <label>
+        Per page:
+        <select v-model.number="perPage" @change="onPerPage">
+          <option :value="12">12</option>
+          <option :value="24">24</option>
+          <option :value="48">48</option>
+        </select>
+      </label>
+    </div>
+
+    <div class="filters">
+      <div v-for="(agg, key) in facets" :key="key" class="facet">
+        <strong>{{ key }}</strong>
+        <ul>
+          <li v-for="(b, idx) in bucketsFor(agg)" :key="idx">{{ b.key }} ({{ b.doc_count }})</li>
+        </ul>
+      </div>
+    </div>
+
+    <ResultList :hits="hits" :loading="loading">
+      <template #item="{ hit }">
+        <div>
+          <h3>{{ hit.title || hit.name }}</h3>
+          <p v-if="hit.description">{{ hit.description }}</p>
+          <small v-if="hit.location">{{ hit.location.lat }}, {{ hit.location.lon }}</small>
+        </div>
+      </template>
+    </ResultList>
+
+    <pagination :page="page" :totalPages="totalPages" @change="onPageChange" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { watch, computed } from 'vue'
+import useSearchkit from '../../composables/useSearchkit'
+import SearchInput from '../molecules/SearchInput.vue'
+import autocomplete from './autocomplete.vue'
+import ResultList from '../molecules/resultList.vue'
+import pagination from '../molecules/pagination.vue'
+
+const { query, hits, loading, page, perPage, facets, totalPages, search, setPage, setPerPage, setSemantic, ranking } = useSearchkit()
+
+const semanticEnabled = computed({ get: () => false, set: (v: boolean) => setSemantic(v) })
+
+function onSearch() {
+  page.value = 1
+  return search()
+}
+
+function onInput(val: string) {
+  query.value = val
+}
+
+function onSelect(item: any) {
+  // if suggestion contains a query text or id, perform targeted search
+  query.value = item.query || item.title || item.name || query.value
+  search()
+}
+
+function onPageChange(p: number) {
+  return setPage(p)
+}
+
+function onPerPage(e: any) {
+  return setPerPage(parseInt(e.target.value || '12', 10))
+}
+
+function toggleSemantic(e: Event) {
+  const target = e.target as HTMLInputElement
+  return setSemantic(target.checked)
+}
+
+function onRankingChange(e: Event) {
+  const target = e.target as HTMLSelectElement
+  ranking.value = target.value as any
+  return search()
+}
+
+function bucketsFor(agg: any) {
+  return (agg && (agg.buckets || agg.terms || agg)) || []
+}
+
+// initialize
+search()
+
+watch(query, () => {
+  // do not auto-search on every keystroke by default; controlled via SearchInput
+})
+</script>
+
+<style scoped>
+.controls { display:flex; gap:12px; align-items:center; flex-wrap:wrap }
+.filters { margin-top:12px; display:flex; gap:16px }
+.facet { background:#fafafa; padding:8px; border:1px solid #eee }
+</style>

package/app/components/molecules/SearchInput.vue

@@ -0,0 +1,39 @@
+<template>
+  <div class="search-input">
+    <input
+      :placeholder="placeholder"
+      :value="modelValue"
+      @input="onInput"
+      @keydown.enter.prevent="onEnter"
+      class="search-input-field"
+    />
+    <button @click="onSearch" class="search-input-button">Search</button>
+  </div>
+</template>
+
+<script setup lang="ts">
+const props = defineProps({
+  modelValue: { type: String, default: '' },
+  placeholder: { type: String, default: 'Search...' },
+})
+const emit = defineEmits(['update:modelValue', 'search'])
+
+function onInput(e: Event) {
+  const v = (e.target as HTMLInputElement).value
+  emit('update:modelValue', v)
+}
+
+function onEnter() {
+  emit('search')
+}
+
+function onSearch() {
+  emit('search')
+}
+</script>
+
+<style scoped>
+.search-input { display:flex; gap:8px; align-items:center }
+.search-input-field { padding:8px; border:1px solid #ccc; }
+.search-input-button { padding:8px 12px }
+</style>

package/app/components/molecules/pagination.vue

@@ -0,0 +1,21 @@
+<template>
+  <div class="pagination">
+    <button :disabled="page <= 1" @click="change(page - 1)">Prev</button>
+    <span class="page-info">Page {{ page }} / {{ totalPages }}</span>
+    <button :disabled="page >= totalPages" @click="change(page + 1)">Next</button>
+  </div>
+</template>
+
+<script setup lang="ts">
+const props = defineProps({ page: { type: Number, default: 1 }, totalPages: { type: Number, default: 1 } })
+const emit = defineEmits(['change'])
+
+function change(p: number) {
+  emit('change', p)
+}
+</script>
+
+<style scoped>
+.pagination { display:flex; gap:12px; align-items:center }
+.page-info { font-weight:600 }
+</style>

package/app/components/molecules/resultList.vue

@@ -0,0 +1,48 @@
+<template>
+    <div class="result-list">
+        <div v-if="loading" class="loading">Loading…</div>
+        <div v-else>
+            <div v-if="!hits || hits.length === 0" class="empty">No results</div>
+            <div v-else>
+                <div v-for="(hit, idx) in hits" :key="idx" class="result-item">
+                    <slot name="item" :hit="hit">
+                        <pre>{{ hit }}</pre>
+                    </slot>
+                </div>
+            </div>
+        </div>
+    </div>
+</template>
+
+<script setup lang="ts">
+    const props = defineProps({
+        hits: {
+            type: (Array as any) as () => Array<any>,
+            default: () => []
+        },
+        loading: {
+            type: Boolean,
+            default: false
+        }
+    })
+</script>
+
+<style scoped>
+    .result-list {
+        display: block
+    }
+
+    .result-item {
+        padding: 12px;
+        border-bottom: 1px solid #eee
+    }
+
+    .loading {
+        padding: 12px
+    }
+
+    .empty {
+        padding: 12px;
+        color: #666
+    }
+</style>

package/app/components/search.vue

@@ -0,0 +1,87 @@
+<template>
+  <div class="searchField">
+    <div class="container">
+      <ais-instant-search :search-client="searchClient" :index-name="indexName">
+        <ais-configure :hits-per-page.camel="8" />
+        <div class="search-panel">
+          <div class="search-panel__filters">
+            <ais-panel>
+              <template v-slot:header>type</template>
+              <ais-refinement-list attribute="type" />
+            </ais-panel>
+
+            <ais-panel>
+              <template v-slot:header>actors</template>
+              <ais-refinement-list searchable attribute="actors" />
+            </ais-panel>
+          </div>
+
+          <div class="search-panel__results">
+            <div class="searchbox">
+              <ais-search-box placeholder="" />
+              <v-text-field v-if="isDev" v-model="searchQuery" placeholder="Debug: search input" class="debug-search-input"></v-text-field>
+            </div>
+            <ais-hits>
+              <template v-slot:item="{ item, index }">
+                <article @click="openResult(item)" style="cursor:pointer">
+                  <h1>
+                    <ais-highlight attribute="title" :hit="item" />
+                  </h1>
+                  <p>
+                    <ais-snippet :hit="item" attribute="plot" />
+                  </p>
+                </article>
+              </template>
+            </ais-hits>
+
+            <div class="pagination">
+              <ais-pagination />
+            </div>
+          </div>
+        </div>
+      </ais-instant-search>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+  import {
+    useRouter
+  } from 'vue-router'
+
+  import {
+    type Ref,
+    ref,
+    watch
+  } from 'vue';
+  import Client from '@searchkit/instantsearch-client'
+
+  const searchClient = Client({
+    url: '/api/search'
+  })
+
+  const configDetails = useRuntimeConfig()
+
+  const router = useRouter()
+  const searchQuery = ref('');
+  const indexName = configDetails.public.indexName;
+  const isDev = process.env.NODE_ENV !== 'production'
+
+
+  if (process.env.NODE_ENV !== 'production') {
+    // eslint-disable-next-line no-console
+    console.debug('[search] searchClient', searchClient, 'has search method:', typeof searchClient.search)
+  }
+
+  function openResult(item: any) {
+    const id = item._id ?? item.id ?? '';
+    const title = item.title ?? '';
+    router.push({
+      path: '/results',
+      query: {
+        id,
+        title
+      }
+    });
+  }
+</script>

package/app/composables/adapter/mock.ts

@@ -0,0 +1,26 @@
+import type { MeeoviSearchItem } from './types'
+import type { BuiltSearchQuery } from '../core/QueryBuilder'
+
+export function createMockSearchAdapter(items: MeeoviSearchItem[] = []) {
+  const cfg = { provider: 'mock' }
+
+  const adapter = {
+    id: 'search:mock',
+    type: 'search',
+    config: cfg,
+
+    async search(query: BuiltSearchQuery | any) {
+      const term = String((query && (query.term || query.params?.q)) || '')
+      const filtered = items.filter((item) => item.title?.toLowerCase().includes(term.toLowerCase()))
+
+      return {
+        items: filtered,
+        total: filtered.length,
+        page: 1,
+        pageSize: filtered.length
+      }
+    }
+  }
+
+  return adapter
+}