@md-plugins/search-ui 0.1.0-rc.9

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present MD-Plugins
+
+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,97 @@
+# @md-plugins/search-ui
+
+Framework-agnostic search UI for search indexes generated by
+`@md-plugins/vite-search-plugin`.
+
+The package provides:
+
+- a static JSON search provider for `search/search-index.json`
+- normalized search result types
+- the `<md-search>` Web Component
+- CSS custom properties and `part` attributes for site-specific styling
+- an icon-only mobile trigger that keeps search available in narrow headers
+
+## Installation
+
+```bash
+pnpm add @md-plugins/search-ui
+```
+
+## Static JSON Usage
+
+```ts
+import { defineMdSearchElement } from '@md-plugins/search-ui'
+
+defineMdSearchElement()
+```
+
+```html
+<md-search src="/search/search-index.json"></md-search>
+```
+
+Search results collapse duplicate records by default. This keeps generated heading/content pairs
+that point to the same URL from appearing twice in the panel. Add `show-duplicate-results` when
+you want to inspect the raw index output:
+
+```html
+<md-search src="/search/search-index.json" show-duplicate-results></md-search>
+```
+
+## Styling
+
+The component uses Shadow DOM, CSS custom properties, and `part` attributes:
+
+```css
+md-search {
+  --md-search-accent: #1976d2;
+  --md-search-surface: white;
+  --md-search-text: #102033;
+  --md-search-radius: 14px;
+}
+
+md-search::part(dialog) {
+  box-shadow: 0 24px 80px rgb(0 0 0 / 24%);
+}
+```
+
+The component supports light and dark modes. By default it follows `prefers-color-scheme`. Use the
+`theme` attribute when your application owns the active theme:
+
+```html
+<md-search src="/search/search-index.json" theme="dark"></md-search>
+```
+
+Use `theme="light"` to force light mode. Site CSS variables can still override either theme.
+
+## Accessibility
+
+`<md-search>` includes keyboard and screen-reader support:
+
+- `Ctrl+K` / `Cmd+K` opens the search by default.
+- `Escape` closes the dialog.
+- `ArrowUp` and `ArrowDown` move between results.
+- `Enter` selects the active result.
+- The dialog uses `role="dialog"` and `aria-modal`.
+- The input exposes combobox/listbox relationships through ARIA attributes.
+- Result rows use `role="option"` and update the active descendant.
+
+Use `search-label` to provide a project-specific input label:
+
+```html
+<md-search src="/search/search-index.json" search-label="Search product documentation"></md-search>
+```
+
+## Custom Providers
+
+```ts
+import { createSearch } from '@md-plugins/search-ui'
+
+createSearch({
+  target: document.querySelector('#search')!,
+  provider: {
+    async search(query) {
+      return mySearchService(query)
+    },
+  },
+})
+```

package/dist/index.d.mts

@@ -0,0 +1,133 @@
+type MaybePromise<T> = T | Promise<T>;
+type SearchRecordType = 'page' | 'heading' | 'content';
+interface SearchRecordSource {
+    file: string;
+    relativeFile: string;
+}
+interface SearchRecord {
+    id: string;
+    type: SearchRecordType;
+    title: string;
+    content: string;
+    url: string;
+    path: string;
+    anchor?: string;
+    section?: string;
+    hierarchy: string[];
+    tags: string[];
+    source: SearchRecordSource;
+    meta?: Record<string, unknown>;
+}
+interface SearchIndex {
+    generatedAt: string;
+    recordCount: number;
+    records: SearchRecord[];
+}
+interface SearchResult {
+    id: string;
+    title: string;
+    url: string;
+    content: string;
+    score: number;
+    type: SearchRecordType;
+    path: string;
+    section?: string;
+    hierarchy: string[];
+    tags: string[];
+    record: SearchRecord;
+}
+interface SearchOptions {
+    limit?: number;
+    collapseDuplicateResults?: boolean;
+}
+interface SearchProvider {
+    search: (query: string, options?: SearchOptions) => MaybePromise<SearchResult[]>;
+}
+interface JsonSearchProviderOptions {
+    src?: string;
+    index?: SearchIndex | SearchRecord[];
+    fetcher?: typeof fetch;
+}
+interface MdSearchSelectEventDetail {
+    result: SearchResult;
+}
+interface CreateSearchOptions {
+    target: Element;
+    src?: string;
+    provider?: SearchProvider;
+    placeholder?: string;
+    triggerLabel?: string;
+    panelTitle?: string;
+    searchLabel?: string;
+    theme?: 'light' | 'dark';
+    shortcut?: string;
+    minQueryLength?: number;
+    maxResults?: number;
+    showDuplicateResults?: boolean;
+}
+
+declare const HTMLElementBase: {
+    new (): HTMLElement;
+    prototype: HTMLElement;
+};
+declare class MdSearchElement extends HTMLElementBase {
+    static observedAttributes: string[];
+    provider?: SearchProvider;
+    private readonly root;
+    private readonly elementId;
+    private results;
+    private query;
+    private opened;
+    private loading;
+    private errorMessage;
+    private activeIndex;
+    private searchTimer;
+    private searchRequestId;
+    private selectionStart;
+    private selectionEnd;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string): void;
+    open(): void;
+    close(): void;
+    toggle(): void;
+    private get src();
+    private get placeholder();
+    private get triggerLabel();
+    private get panelTitle();
+    private get searchLabel();
+    private get shortcut();
+    private get minQueryLength();
+    private get maxResults();
+    private get showDuplicateResults();
+    private get activeResult();
+    private getProvider;
+    private readonly onGlobalKeydown;
+    private readonly onInput;
+    private readonly onDialogKeydown;
+    private runSearch;
+    private focusInput;
+    private setActiveIndex;
+    private syncInputAria;
+    private syncActiveResult;
+    private selectResult;
+    private bindResultEvents;
+    private renderResultsContainer;
+    private renderResults;
+    private render;
+    private bindEvents;
+}
+declare function defineMdSearchElement(name?: string): void;
+declare function createSearch(options: CreateSearchOptions): MdSearchElement;
+
+declare function searchRecords(records: SearchRecord[], query: string, options?: SearchOptions): SearchResult[];
+declare function createStaticSearchProvider(records: SearchRecord[]): SearchProvider;
+declare function createJsonSearchProvider(options?: JsonSearchProviderOptions): SearchProvider;
+
+declare function normalizeSearchQuery(value: string): string;
+declare function createSearchTerms(query: string): string[];
+declare function normalizeSearchableText(value: unknown): string;
+declare function createSearchSnippet(content: string, terms: string[], length?: number): string;
+
+export { MdSearchElement, createJsonSearchProvider, createSearch, createSearchSnippet, createSearchTerms, createStaticSearchProvider, defineMdSearchElement, normalizeSearchQuery, normalizeSearchableText, searchRecords };
+export type { CreateSearchOptions, JsonSearchProviderOptions, MaybePromise, MdSearchSelectEventDetail, SearchIndex, SearchOptions, SearchProvider, SearchRecord, SearchRecordSource, SearchRecordType, SearchResult };

package/dist/index.d.ts

@@ -0,0 +1,133 @@
+type MaybePromise<T> = T | Promise<T>;
+type SearchRecordType = 'page' | 'heading' | 'content';
+interface SearchRecordSource {
+    file: string;
+    relativeFile: string;
+}
+interface SearchRecord {
+    id: string;
+    type: SearchRecordType;
+    title: string;
+    content: string;
+    url: string;
+    path: string;
+    anchor?: string;
+    section?: string;
+    hierarchy: string[];
+    tags: string[];
+    source: SearchRecordSource;
+    meta?: Record<string, unknown>;
+}
+interface SearchIndex {
+    generatedAt: string;
+    recordCount: number;
+    records: SearchRecord[];
+}
+interface SearchResult {
+    id: string;
+    title: string;
+    url: string;
+    content: string;
+    score: number;
+    type: SearchRecordType;
+    path: string;
+    section?: string;
+    hierarchy: string[];
+    tags: string[];
+    record: SearchRecord;
+}
+interface SearchOptions {
+    limit?: number;
+    collapseDuplicateResults?: boolean;
+}
+interface SearchProvider {
+    search: (query: string, options?: SearchOptions) => MaybePromise<SearchResult[]>;
+}
+interface JsonSearchProviderOptions {
+    src?: string;
+    index?: SearchIndex | SearchRecord[];
+    fetcher?: typeof fetch;
+}
+interface MdSearchSelectEventDetail {
+    result: SearchResult;
+}
+interface CreateSearchOptions {
+    target: Element;
+    src?: string;
+    provider?: SearchProvider;
+    placeholder?: string;
+    triggerLabel?: string;
+    panelTitle?: string;
+    searchLabel?: string;
+    theme?: 'light' | 'dark';
+    shortcut?: string;
+    minQueryLength?: number;
+    maxResults?: number;
+    showDuplicateResults?: boolean;
+}
+
+declare const HTMLElementBase: {
+    new (): HTMLElement;
+    prototype: HTMLElement;
+};
+declare class MdSearchElement extends HTMLElementBase {
+    static observedAttributes: string[];
+    provider?: SearchProvider;
+    private readonly root;
+    private readonly elementId;
+    private results;
+    private query;
+    private opened;
+    private loading;
+    private errorMessage;
+    private activeIndex;
+    private searchTimer;
+    private searchRequestId;
+    private selectionStart;
+    private selectionEnd;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string): void;
+    open(): void;
+    close(): void;
+    toggle(): void;
+    private get src();
+    private get placeholder();
+    private get triggerLabel();
+    private get panelTitle();
+    private get searchLabel();
+    private get shortcut();
+    private get minQueryLength();
+    private get maxResults();
+    private get showDuplicateResults();
+    private get activeResult();
+    private getProvider;
+    private readonly onGlobalKeydown;
+    private readonly onInput;
+    private readonly onDialogKeydown;
+    private runSearch;
+    private focusInput;
+    private setActiveIndex;
+    private syncInputAria;
+    private syncActiveResult;
+    private selectResult;
+    private bindResultEvents;
+    private renderResultsContainer;
+    private renderResults;
+    private render;
+    private bindEvents;
+}
+declare function defineMdSearchElement(name?: string): void;
+declare function createSearch(options: CreateSearchOptions): MdSearchElement;
+
+declare function searchRecords(records: SearchRecord[], query: string, options?: SearchOptions): SearchResult[];
+declare function createStaticSearchProvider(records: SearchRecord[]): SearchProvider;
+declare function createJsonSearchProvider(options?: JsonSearchProviderOptions): SearchProvider;
+
+declare function normalizeSearchQuery(value: string): string;
+declare function createSearchTerms(query: string): string[];
+declare function normalizeSearchableText(value: unknown): string;
+declare function createSearchSnippet(content: string, terms: string[], length?: number): string;
+
+export { MdSearchElement, createJsonSearchProvider, createSearch, createSearchSnippet, createSearchTerms, createStaticSearchProvider, defineMdSearchElement, normalizeSearchQuery, normalizeSearchableText, searchRecords };
+export type { CreateSearchOptions, JsonSearchProviderOptions, MaybePromise, MdSearchSelectEventDetail, SearchIndex, SearchOptions, SearchProvider, SearchRecord, SearchRecordSource, SearchRecordType, SearchResult };