@crombolo/render 0.13.1 → 0.14.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crombolo/render",
-  "version": "0.13.1",
+  "version": "0.14.1",
   "description": "TSX server rendering and the published-content model for crombolo.",
   "license": "MIT",
   "author": "Crombolo",
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@crombolo/core": "0.13.1",
+    "@crombolo/core": "0.14.1",
     "@types/react": "^19.3.0"
   }
 }

package/src/context.ts

@@ -12,9 +12,12 @@
 import { AsyncLocalStorage } from 'node:async_hooks'
 import type { Child } from './jsx-runtime.ts'
 import type { PageProps } from './model.ts'
+import type { SiteSearchPort } from './search.ts'
 
 interface RenderScope {
   page: PageProps | undefined
+  /** The site search the server scoped to the person asking, when it provides one. */
+  search?: SiteSearchPort
   contexts: ReadonlyMap<symbol, unknown>
   /** Shared by every scope a provider opens inside one render, so ids stay unique. */
   ids: { next: number }
@@ -30,8 +33,8 @@ if (!shared[KEY]) shared[KEY] = new AsyncLocalStorage<RenderScope>()
 const store = shared[KEY] as AsyncLocalStorage<RenderScope>
 
 /** Runs a render with `page` available to `usePage()`, and ids counted from zero. */
-export function renderScope<T>(page: PageProps, render: () => T): T {
-  return store.run({ page, contexts: new Map(), ids: { next: 0 } }, render)
+export function renderScope<T>(page: PageProps, render: () => T, search?: SiteSearchPort): T {
+  return store.run({ page, search, contexts: new Map(), ids: { next: 0 } }, render)
 }
 
 function within(caller: string): RenderScope {
@@ -56,6 +59,14 @@ export function usePage<Properties = any>(): PageProps<Properties> {
   return page as PageProps<Properties>
 }
 
+/** The page and the site search for `search()`, which lives in `search.ts`. */
+export function currentSiteSearch(): { page: PageProps; search: SiteSearchPort | undefined } {
+  const scope = within('search()')
+  if (!scope.page)
+    throw new Error('search() was called inside a context Provider rendered outside a page.')
+  return { page: scope.page, search: scope.search }
+}
+
 /**
  * An id unique within this render, for tying a label to its input or an
  * `aria-describedby` to its text. Not for CSS selectors: the colons need escaping.
@@ -100,7 +111,10 @@ export function createContext<T>(defaultValue: T): Context<T> {
     const outer = store.getStore()
     const contexts = new Map(outer?.contexts)
     contexts.set(key, value)
-    return store.run({ page: outer?.page, contexts, ids: outer?.ids ?? { next: 0 } }, children)
+    return store.run(
+      { page: outer?.page, search: outer?.search, contexts, ids: outer?.ids ?? { next: 0 } },
+      children,
+    )
   }
   return Object.assign(Provider, { Provider, defaultValue, key }) as Context<T>
 }

package/src/excerpt.ts

@@ -0,0 +1,118 @@
+/**
+ * Search excerpts: the stretch of a page's text around the words searched for,
+ * with each matching word marked. Words are compared folded — lowercase, no
+ * diacritics — exactly as the index matches them, and a word matches a query
+ * word it starts with. Pure, so both dialects give the same excerpt.
+ */
+
+/** A page's text by weight, as the site-search index keeps it. */
+export interface SearchableText {
+  name: string
+  high: readonly string[]
+  normal: readonly string[]
+  low: readonly string[]
+}
+
+/** A run of excerpt text; `match` when it is a word the query matched. */
+export interface ExcerptSegment {
+  text: string
+  match: boolean
+}
+
+const WORD = /[\p{L}\p{N}]+/gu
+
+/** A word as the index stores it: decomposed, diacritics stripped, lowercase. */
+export function foldWord(word: string): string {
+  return word
+    .normalize('NFKD')
+    .replace(/\p{M}+/gu, '')
+    .toLowerCase()
+}
+
+/** The folded words of a query. */
+export function queryWords(query: string): string[] {
+  return [...new Set((query.match(WORD) ?? []).map(foldWord).filter(Boolean))]
+}
+
+const matches = (word: string, terms: readonly string[]) => {
+  const folded = foldWord(word)
+  return terms.some((term) => folded.startsWith(term))
+}
+
+/**
+ * About `length` characters of the page's text around the first matching
+ * word, taken from its highest-weighted text that matches, else from the start
+ * of its text. Ends that were cut are marked with an ellipsis.
+ */
+export function excerpt(text: SearchableText, query: string, length = 200): ExcerptSegment[] {
+  const terms = queryWords(query)
+  const fields = [text.high, text.normal, text.low]
+    .map((field) => field.join(' … ').replace(/\s+/g, ' ').trim())
+    .filter(Boolean)
+  if (fields.length === 0) return []
+  let source = fields[0] as string
+  let first = -1
+  for (const field of fields) {
+    const hit = [...field.matchAll(WORD)].find((m) => matches(m[0], terms))
+    if (hit) {
+      source = field
+      first = hit.index
+      break
+    }
+  }
+
+  let start = first < 0 ? 0 : Math.max(0, first - Math.floor(length / 3))
+  let end = Math.min(source.length, start + length)
+  if (end - start < length) start = Math.max(0, end - length)
+  // Cut at spaces, so no word is shown in part.
+  if (start > 0) {
+    const space = source.indexOf(' ', start)
+    if (space >= 0 && space < (first < 0 ? end : first)) start = space + 1
+  }
+  if (end < source.length) {
+    const space = source.lastIndexOf(' ', end)
+    if (space > start) end = space
+  }
+  // A cut that lands on the separator between two texts keeps one ellipsis, not two.
+  const window = source
+    .slice(start, end)
+    .replace(/^(?:…\s*)+/, '')
+    .replace(/(?:\s*…)+$/, '')
+
+  const segments: ExcerptSegment[] = []
+  const push = (value: string, match: boolean) => {
+    if (!value) return
+    const last = segments[segments.length - 1]
+    if (last && last.match === match) last.text += value
+    else segments.push({ text: value, match })
+  }
+  if (start > 0) push('… ', false)
+  let at = 0
+  for (const word of window.matchAll(WORD)) {
+    if (!matches(word[0], terms)) continue
+    push(window.slice(at, word.index), false)
+    push(word[0], true)
+    at = word.index + word[0].length
+  }
+  push(window.slice(at), false)
+  if (end < source.length) push(' …', false)
+  return segments
+}
+
+const ESCAPES: Record<string, string> = {
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&#39;',
+}
+
+/** An excerpt as HTML: every segment escaped, the matches in `<mark>`. */
+export function excerptHtml(segments: readonly ExcerptSegment[]): string {
+  return segments
+    .map((segment) => {
+      const text = segment.text.replace(/[&<>"']/g, (c) => ESCAPES[c] as string)
+      return segment.match ? `<mark>${text}</mark>` : text
+    })
+    .join('')
+}

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from './context.ts'
+export * from './excerpt.ts'
 export * from './form-script.ts'
 export * from './forms.ts'
 export * from './html.ts'
@@ -9,7 +10,9 @@ export * from './model.ts'
 export * from './published-cache.ts'
 export * from './redirects.ts'
 export * from './renderer.ts'
+export * from './search.ts'
 export * from './seo.ts'
+export * from './sign-in.ts'
 export * from './sitemap.ts'
 export * from './snapshots.ts'
 export * from './url-segment.ts'

package/src/renderer.ts

@@ -15,6 +15,7 @@ import { RawHtml } from './html.ts'
 import { type Child, renderToString } from './jsx-runtime.ts'
 import type { PageProps, PublishedContent, RequestMember } from './model.ts'
 import { type PublishedCache, translate, urlsIn } from './published-cache.ts'
+import type { SiteSearchPort } from './search.ts'
 import { absoluteUrl, type SeoSiteDefaults } from './seo.ts'
 import type { ViewSnapshots } from './snapshots.ts'
 
@@ -95,6 +96,8 @@ export interface RenderRequest {
   seo?: SeoSiteDefaults
   /** Aborts when nobody is waiting for the page any more: the visitor disconnected. */
   signal?: AbortSignal
+  /** Site search scoped to whoever is asking, for `search()`. */
+  search?: SiteSearchPort
 }
 
 /**
@@ -322,7 +325,7 @@ export class Renderer {
     }
 
     // Inside the page's scope, so any component can ask for it with `usePage()`.
-    return renderScope(props, () => this.#renderLayouts(alias, props, rendering))
+    return renderScope(props, () => this.#renderLayouts(alias, props, rendering), request.search)
   }
 
   async #renderLayouts(

package/src/search.ts

@@ -0,0 +1,61 @@
+/**
+ * Site search from a component (story 140). The server answers it from the
+ * published-only index, leaving out pages the signed-in member — or a visitor
+ * who is not signed in — may not open, and hands back each page as published
+ * content with an excerpt around the words searched for.
+ */
+import { currentSiteSearch } from './context.ts'
+import type { ExcerptSegment } from './excerpt.ts'
+import type { PublishedContent } from './model.ts'
+
+export interface SearchOptions {
+  /** The culture searched; the page's own when absent. */
+  culture?: string | null
+  /** Content type aliases to keep to; every searchable type when absent. */
+  types?: readonly string[]
+  skip?: number
+  take?: number
+}
+
+export interface SearchResult {
+  content: PublishedContent
+  url: string
+  name: string
+  score: number
+  /** The text around the words searched for; render `match` segments marked. */
+  excerpt: ExcerptSegment[]
+}
+
+export interface SearchResults {
+  /** Every match the person searching may open, not only this page of them. */
+  total: number
+  items: SearchResult[]
+}
+
+/** What the server provides a render: a search already scoped to the person asking. */
+export type SiteSearchPort = (
+  query: string,
+  options: { culture: string | null; types: readonly string[]; skip: number; take: number },
+) => Promise<SearchResults>
+
+/**
+ * Searches the site's published pages, best match first:
+ *
+ * ```tsx
+ * const results = await search(q, { take: 10, skip: (page - 1) * 10 })
+ * ```
+ *
+ * Every word of the query must be in a page, by the start of a word; the name
+ * counts most, then the properties marked `site-search = "high"`, the rest,
+ * and those marked `"low"`.
+ */
+export async function search(query: string, options: SearchOptions = {}): Promise<SearchResults> {
+  const { page, search: port } = currentSiteSearch()
+  if (!port) throw new Error('Site search is not available to this render.')
+  return port(query, {
+    culture: options.culture === undefined ? page.culture : options.culture,
+    types: options.types ?? [],
+    skip: Math.max(0, Math.floor(options.skip ?? 0)),
+    take: Math.min(100, Math.max(1, Math.floor(options.take ?? 10))),
+  })
+}

package/src/sign-in.ts

@@ -0,0 +1,14 @@
+/**
+ * Links for signing in through a member identity provider (story 031), for a
+ * site's login form: `<a href={externalSignInUrl('entra', returnUrl)}>`. The
+ * provider is one the site's config lists in `memberIdentityProviders`, by id.
+ */
+
+/** Where member sign-ins through an identity provider start. */
+export const MEMBER_EXTERNAL_SIGN_IN_PATH = '/umbraco/members/external'
+
+/** The URL that signs a member in through a provider, coming back to `returnUrl` (a path on this site). */
+export function externalSignInUrl(providerId: string, returnUrl?: string): string {
+  const query = returnUrl ? `?returnUrl=${encodeURIComponent(returnUrl)}` : ''
+  return `${MEMBER_EXTERNAL_SIGN_IN_PATH}/${encodeURIComponent(providerId)}${query}`
+}