forgebook 0.1.8 → 0.3.0

package/dist/src/search.d.ts

@@ -0,0 +1,154 @@
+/**
+ * The catalogue's search across everything: components, stories, docs pages, props and the text of the documentation,
+ * ranked as `forgebook find` ranks, so a person and an agent asking the same words get the same answer.
+ *
+ * @remarks
+ * A page or a component is one result, and what matched inside it are its hits: a person looks for a place first and a
+ * line second, and a word found in a component's name and another in one of its stories is one good answer, not two
+ * half ones. A word is worth what it is worth where it counts most in the result (`searchMatch.ts`), so the ranking is
+ * `findComponents`' with more places. A result that holds every word comes before one that does not, which says what it
+ * missed. Everything is read from the tree and the index (`searchIndex.ts`), with no server, so the same code answers
+ * in the page and on the dev server. Pure.
+ *
+ * @module
+ */
+import type { SearchIndex } from "./searchIndex.ts";
+import { type MarkedText } from "./searchMarks.ts";
+import { type SearchPlace } from "./searchMatch.ts";
+import { type StoryTree } from "./storyTree.ts";
+/** Where a result or a hit goes: a page of the catalogue, at a heading or a prop when it has one. */
+export type SearchTarget = ComponentTarget | PageTarget | {
+    /** A story's page. */
+    readonly kind: "story";
+    /** Its id. */
+    readonly id: string;
+};
+/** A component's page, at a heading or a prop when it has one. */
+export type ComponentTarget = {
+    /** What it is. */
+    readonly kind: "component";
+    /** Its id. */
+    readonly id: string;
+    /** The heading or the prop it opens at. */
+    readonly anchor?: string;
+};
+/** A docs page, at a heading when it has one. */
+export type PageTarget = {
+    /** What it is. */
+    readonly kind: "page";
+    /** Its id. */
+    readonly id: string;
+    /** The heading it opens at. */
+    readonly anchor?: string;
+};
+/** What a line of a result is: a kind of thing a word can be found in. */
+export type SearchHitKind = "description" | "story" | "prop" | "event" | "heading" | "text";
+/** Why a result's own name is there: where in its name, words or place a word of the query is. */
+export type SearchReason = {
+    /** Where it is. */
+    readonly place: "name" | "keyword" | "title";
+    /** What stands there, when it is another word for the one asked (`modal` finding `dialog`). */
+    readonly means?: string;
+};
+/** A line of a result: something inside it that matched. */
+export type SearchHit = {
+    /** What it is. */
+    readonly kind: SearchHitKind;
+    /** Its name, marked: the prop, the story, the heading; none for plain text. */
+    readonly label?: readonly MarkedText[];
+    /** The text around the match, marked. */
+    readonly snippet: readonly MarkedText[];
+    /** Where it goes. */
+    readonly target: SearchTarget;
+};
+/** A result: a component or a docs page. */
+export type SearchResult = {
+    /** What it is. */
+    readonly kind: "component" | "page";
+    /** Where it goes. */
+    readonly target: ComponentTarget | PageTarget;
+    /** Its name, marked. */
+    readonly name: readonly MarkedText[];
+    /** Where it sits: its source and its place. */
+    readonly place: string;
+    /** How well it matches: higher is better, only comparable within an answer. */
+    readonly score: number;
+    /** The words of the query it holds. */
+    readonly matched: readonly string[];
+    /** The words of the query it does not. */
+    readonly missed: readonly string[];
+    /** Why its name is there; none when only what is inside it matched. */
+    readonly reasons: readonly SearchReason[];
+    /** The best of what matched inside it. */
+    readonly hits: readonly SearchHit[];
+    /** How many things inside it matched, those not listed included. */
+    readonly hitCount: number;
+};
+/** An answer. */
+export type SearchAnswer = {
+    /** The results, best first. */
+    readonly results: readonly SearchResult[];
+    /** How many there are, those past the limit included. */
+    readonly total: number;
+};
+/** How much of an answer to give. */
+export type SearchLimits = {
+    /** How many results. */
+    readonly results: number;
+    /** How many hits of each. */
+    readonly hits: number;
+};
+/** What the search reads of something inside a result. */
+type Field = {
+    /** What it is. */
+    readonly kind: SearchHitKind | SearchReason["place"];
+    /** Its name; none for plain text. */
+    readonly label: string | undefined;
+    /** Its text. */
+    readonly text: string;
+    /** Its name's words. */
+    readonly labelWords: readonly string[];
+    /** Its text's words. */
+    readonly textWords: readonly string[];
+    /** Its name's and its text's words in order, each between spaces, as the words of a query are looked for in them. */
+    readonly sentences: readonly string[];
+    /** Where it goes. */
+    readonly target: SearchTarget;
+};
+/** A component or a docs page, read for the search. */
+export type Searchable = {
+    /** What it is. */
+    readonly kind: SearchResult["kind"];
+    /** Where it goes. */
+    readonly target: SearchResult["target"];
+    /** Its name. */
+    readonly name: string;
+    /** Where it sits. */
+    readonly place: string;
+    /** What is in it. */
+    readonly fields: readonly Field[];
+    /** Its words, by where they are. */
+    readonly parts: Partial<Record<SearchPlace, readonly string[]>>;
+};
+/**
+ * Everything the search can find in a catalogue.
+ *
+ * @param tree - the tree: names, keywords and stories, there from the first screen.
+ * @param indexes - each source's index, by its id: what it adds is found once it is there.
+ */
+export declare const searchables: (tree: StoryTree, indexes: ReadonlyMap<string, SearchIndex>) => readonly Searchable[];
+/** The most of a query that is read: a page pasted by mistake must not hold the tab for seconds. */
+export declare const MAX_QUERY = 200;
+/**
+ * What a query finds.
+ *
+ * @remarks
+ * Where something holds every word, what holds much less is left out: `the` must not bring the whole catalogue along
+ * with a sentence copied from a page. Nothing holding every word, the nearest are given, each saying what it missed.
+ *
+ * @param all - everything that can be found (`searchables`).
+ * @param query - what was typed.
+ * @param limits - how much of the answer to give.
+ */
+export declare const searchCatalogue: (all: readonly Searchable[], query: string, limits: SearchLimits) => SearchAnswer;
+export {};

package/dist/src/search.js

@@ -0,0 +1,265 @@
+/**
+ * The catalogue's search across everything: components, stories, docs pages, props and the text of the documentation,
+ * ranked as `forgebook find` ranks, so a person and an agent asking the same words get the same answer.
+ *
+ * @remarks
+ * A page or a component is one result, and what matched inside it are its hits: a person looks for a place first and a
+ * line second, and a word found in a component's name and another in one of its stories is one good answer, not two
+ * half ones. A word is worth what it is worth where it counts most in the result (`searchMatch.ts`), so the ranking is
+ * `findComponents`' with more places. A result that holds every word comes before one that does not, which says what it
+ * missed. Everything is read from the tree and the index (`searchIndex.ts`), with no server, so the same code answers
+ * in the page and on the dev server. Pure.
+ *
+ * @module
+ */
+import { propAnchor } from "./docAnchors.js";
+import { markedText, snippetOf } from "./searchMarks.js";
+import { foldedText, meaningsOf, WEIGHTS, wordMatch, wordsOf, worthOf } from "./searchMatch.js";
+import { componentId } from "./storyTree.js";
+/** Where the words of a field's name count. */
+const LABEL_PLACE = {
+    name: "name",
+    keyword: "keyword",
+    title: "title",
+    description: "description",
+    story: "story",
+    prop: "prop",
+    event: "prop",
+    heading: "heading",
+    text: "text"
+};
+/** Where the words of a field's text count. */
+const TEXT_PLACE = {
+    ...LABEL_PLACE,
+    prop: "description",
+    event: "description",
+    heading: "text"
+};
+/** A name's words, and the name as one word: `onvalue` starts `onValueChange`. */
+const labelWordsOf = (label) => [
+    ...new Set([...wordsOf(label), foldedText(label).replace(/[^\p{L}\p{N}]+/gu, "")])
+];
+/** A text's words in order, each between spaces: `art button` must not be found in `smart buttons`. */
+const sentenceOf = (text) => ` ${wordsOf(text).join(" ")} `;
+/** A field. */
+const fieldOf = (kind, label, written, target) => {
+    // a TSDoc's backticks are marks, which a line of results does not draw
+    const text = written.replaceAll("`", "");
+    return {
+        kind,
+        label,
+        text,
+        labelWords: label === undefined ? [] : labelWordsOf(label),
+        textWords: [...new Set(wordsOf(text))],
+        sentences: [sentenceOf(label ?? ""), sentenceOf(text)],
+        target
+    };
+};
+/** A thing's words, by where they are. */
+const partsOf = (fields) => {
+    const parts = new Map();
+    const add = (place, words) => {
+        const known = parts.get(place) ?? new Set();
+        for (const word of words)
+            known.add(word);
+        parts.set(place, known);
+    };
+    for (const field of fields) {
+        add(LABEL_PLACE[field.kind], field.labelWords);
+        add(TEXT_PLACE[field.kind], field.textWords);
+    }
+    return Object.fromEntries([...parts].map(([place, words]) => [place, [...words]]));
+};
+/** A stretch of documentation as a field of what holds it. */
+const sectionField = (section, target) => {
+    const opened = section.anchor === undefined ? target : { ...target, anchor: section.anchor };
+    return fieldOf(section.heading === undefined ? "text" : "heading", section.heading, section.text, opened);
+};
+/** What the search reads of a component. */
+const componentFields = (component, target, index) => [
+    fieldOf("name", component.name, "", target),
+    fieldOf("title", component.title.split("/").slice(0, -1).join(" "), "", target),
+    ...component.keywords.map((keyword) => fieldOf("keyword", keyword, "", target)),
+    ...(index?.lead === undefined ? [] : [fieldOf("description", undefined, index.lead, target)]),
+    ...(index?.props ?? []).map(({ name, text, part, isEvent }) => fieldOf(isEvent === true ? "event" : "prop", name, text, { ...target, anchor: propAnchor(name, part) })),
+    ...component.stories.map((story) => fieldOf("story", story.name, story.description ?? "", { kind: "story", id: story.id })),
+    ...(index?.sections ?? []).map((section) => sectionField(section, target))
+];
+/** A component, read for the search. */
+const searchableComponent = (source, familyName, groupName, component, index) => {
+    const target = { kind: "component", id: componentId(source.id, component.title) };
+    const fields = componentFields(component, target, index?.components?.[component.file]);
+    return {
+        kind: "component",
+        target,
+        name: component.name,
+        place: [source.name, familyName, groupName].filter((part) => part !== undefined).join(" · "),
+        fields,
+        parts: partsOf(fields)
+    };
+};
+/** A docs page, read for the search. */
+const searchablePage = (source, page, index) => {
+    const target = { kind: "page", id: page.id };
+    const sections = index?.pages?.[page.file] ?? [];
+    const fields = [
+        fieldOf("name", page.name, "", target),
+        fieldOf("title", page.group ?? "", "", target),
+        ...(page.description === undefined ? [] : [fieldOf("description", undefined, page.description, target)]),
+        ...sections.map((section) => sectionField(section, target))
+    ];
+    return {
+        kind: "page",
+        target,
+        name: page.name,
+        place: [source.name, page.group].filter((part) => part !== undefined).join(" · "),
+        fields,
+        parts: partsOf(fields)
+    };
+};
+/**
+ * Everything the search can find in a catalogue.
+ *
+ * @param tree - the tree: names, keywords and stories, there from the first screen.
+ * @param indexes - each source's index, by its id: what it adds is found once it is there.
+ */
+export const searchables = (tree, indexes) => tree.sources.flatMap((source) => {
+    const index = indexes.get(source.id);
+    return [
+        ...source.pages.map((page) => searchablePage(source, page, index)),
+        ...source.families.flatMap((family) => family.groups.flatMap((group) => group.components.map((component) => searchableComponent(source, family.name, group.name, component, index))))
+    ];
+});
+/** How much of a query must be there for a result to stand beside one that holds all of it. */
+const NEAR_SHARE = 0.75;
+/** The most of a query that is read: a page pasted by mistake must not hold the tab for seconds. */
+export const MAX_QUERY = 200;
+/** A query's words and phrase. */
+const queryOf = (typed) => {
+    const query = typed.slice(0, MAX_QUERY);
+    const words = wordsOf(query);
+    const isSeveral = words.length > 1;
+    return {
+        words: [...new Set(words)],
+        phrase: isSeveral ? foldedText(query).replace(/\s+/g, " ").trim() : undefined,
+        sentence: isSeveral ? sentenceOf(query) : undefined
+    };
+};
+/** Whether some word of a list holds a word asked for. */
+const isHeldIn = (words, word) => {
+    const meanings = meaningsOf(word);
+    return words.some((held) => wordMatch(held, word, meanings) !== undefined);
+};
+/** Whether a field holds a query's sentence, in its name or its text. */
+const holdsSentence = (field, sentence) => sentence !== undefined && field.sentences.some((each) => each.includes(sentence));
+/** How a thing answers the query; none when it holds no word of it. */
+const scored = (found, { words, sentence }) => {
+    const worths = words.map((word) => ({ word, worth: worthOf(found.parts, word) }));
+    const sum = worths.reduce((total, each) => total + each.worth, 0);
+    if (sum === 0)
+        return undefined;
+    const hasPhrase = found.fields.some((field) => holdsSentence(field, sentence));
+    return {
+        found,
+        score: sum + (hasPhrase ? WEIGHTS.name : 0),
+        matched: worths.filter((each) => each.worth > 0).map((each) => each.word),
+        missed: worths.filter((each) => each.worth === 0).map((each) => each.word)
+    };
+};
+/** The word that stands in a text for one asked, when it is another word for it. */
+const synonymIn = (words, asked) => {
+    const meant = asked.flatMap((word) => {
+        const meanings = meaningsOf(word);
+        return words.find((held) => held !== word && meanings.includes(held) && !word.startsWith(held)) ?? [];
+    });
+    return meant[0];
+};
+/** Where a thing's name can say why it is there, the place that says most first. */
+const REASON_PLACES = ["name", "keyword", "title"];
+/** Why a thing's own name is there: each word answered once, where it counts most. */
+const reasonsOf = ({ fields }, words) => {
+    let open = words;
+    return REASON_PLACES.flatMap((place) => {
+        const labels = fields.filter((field) => field.kind === place).flatMap((field) => field.labelWords);
+        const held = open.filter((word) => isHeldIn(labels, word));
+        if (held.length === 0)
+            return [];
+        open = open.filter((word) => !held.includes(word));
+        const means = synonymIn(labels, held);
+        return [means === undefined ? { place } : { place, means }];
+    });
+};
+/** Whether a field is a thing inside a result. */
+const isInnerField = (field) => field.kind !== "name" && field.kind !== "keyword" && field.kind !== "title";
+/** A field as a line a result may show; none when it holds nothing. */
+const heldField = (field, { words, sentence }) => {
+    const inLabel = words.filter((word) => isHeldIn(field.labelWords, word));
+    const inText = words.filter((word) => isHeldIn(field.textWords, word));
+    const count = new Set([...inLabel, ...inText]).size;
+    if (count === 0)
+        return undefined;
+    const isInLabel = inLabel.length > 0 && inLabel.length >= inText.length;
+    return {
+        field,
+        isInLabel,
+        count,
+        worth: isInLabel ? WEIGHTS[LABEL_PLACE[field.kind]] : WEIGHTS[TEXT_PLACE[field.kind]],
+        hasPhrase: holdsSentence(field, sentence)
+    };
+};
+/** A field that matched as a line of its result. */
+const hitOf = ({ field, isInLabel }, query) => {
+    const { kind, label, text, target } = field;
+    return {
+        kind: kind === "heading" && !isInLabel ? "text" : kind,
+        ...(label === undefined ? {} : { label: markedText(label, query) }),
+        snippet: snippetOf(text, query),
+        target
+    };
+};
+/** A thing with its hits, as a result. */
+const resultOf = ({ found, score, matched, missed }, query, limit) => {
+    const held = found.fields
+        .filter(isInnerField)
+        .flatMap((field) => heldField(field, query) ?? [])
+        .toSorted((first, second) => Number(second.hasPhrase) - Number(first.hasPhrase) ||
+        second.count - first.count ||
+        second.worth - first.worth);
+    return {
+        kind: found.kind,
+        target: found.target,
+        name: markedText(found.name, query),
+        place: found.place,
+        score,
+        matched,
+        missed,
+        reasons: reasonsOf(found, query.words),
+        hits: held.slice(0, limit).map((each) => hitOf(each, query)),
+        hitCount: held.length
+    };
+};
+/**
+ * What a query finds.
+ *
+ * @remarks
+ * Where something holds every word, what holds much less is left out: `the` must not bring the whole catalogue along
+ * with a sentence copied from a page. Nothing holding every word, the nearest are given, each saying what it missed.
+ *
+ * @param all - everything that can be found (`searchables`).
+ * @param query - what was typed.
+ * @param limits - how much of the answer to give.
+ */
+export const searchCatalogue = (all, query, limits) => {
+    const read = queryOf(query);
+    const found = all
+        .flatMap((each) => scored(each, read) ?? [])
+        .toSorted((first, second) => first.missed.length - second.missed.length ||
+        second.score - first.score ||
+        first.found.name.localeCompare(second.found.name));
+    const hasWhole = found.some((each) => each.missed.length === 0);
+    const kept = found.filter((each) => !hasWhole || each.matched.length >= read.words.length * NEAR_SHARE);
+    return {
+        results: kept.slice(0, limits.results).map((each) => resultOf(each, read, limits.hits)),
+        total: kept.length
+    };
+};

package/dist/src/searchIndex.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The search index: what the search reads that the page does not already hold, as the plugin builds it for each group of
+ * story files and docs pages, and the shell loads on the first search.
+ *
+ * @remarks
+ * The names, keywords and stories are in the tree the sidebar draws, so the index leaves them out and holds only what
+ * would otherwise take opening every component: the props, the descriptions and the text of the documentation. It
+ * crosses from the plugin to the page as data, so it is checked on arrival (`isSearchIndex`). Pure.
+ *
+ * @module
+ */
+/** A stretch of documentation: the text under one heading, or before the first. */
+export type SearchSection = {
+    /** The heading's anchor; none for the text before the first heading. */
+    readonly anchor?: string;
+    /** The heading's text, without marks. */
+    readonly heading?: string;
+    /** The text, plain, without its marks. */
+    readonly text: string;
+};
+/** A prop, an event or a hook's parameter of a component. */
+export type SearchProp = {
+    /** Its name. */
+    readonly name: string;
+    /** What it does; empty when its TSDoc does not say. */
+    readonly text: string;
+    /** The part it belongs to (the meta's `subcomponents`); none for the component's own. */
+    readonly part?: string;
+    /** Whether it is an event, listed under the Events heading. */
+    readonly isEvent?: boolean;
+};
+/** What the search reads of a component beyond the tree. */
+export type SearchComponent = {
+    /** What it is: its file's summary, its TSDoc and when to use it. */
+    readonly lead?: string;
+    /** Its props, events and parameters. */
+    readonly props?: readonly SearchProp[];
+    /** Its documentation file, by heading. */
+    readonly sections?: readonly SearchSection[];
+};
+/** A group's index: its components by story file, its docs pages by file. */
+export type SearchIndex = {
+    /** The components, keyed as the group's files are. */
+    readonly components?: Readonly<Record<string, SearchComponent>>;
+    /** The docs pages' text by heading, keyed as the group's pages are. */
+    readonly pages?: Readonly<Record<string, readonly SearchSection[]>>;
+    /** What could not be read: the rest of the index still works. */
+    readonly problems?: readonly string[];
+};
+/**
+ * Whether a value is a group's index: what its loader gives is unchecked data.
+ *
+ * @param value - what the loader gave.
+ */
+export declare const isSearchIndex: (value: unknown) => value is SearchIndex;
+/**
+ * Several groups' indexes as one: the keys are unique across a source's groups.
+ *
+ * @param indexes - the indexes.
+ */
+export declare const mergedSearchIndex: (indexes: readonly SearchIndex[]) => SearchIndex;

package/dist/src/searchIndex.js

@@ -0,0 +1,55 @@
+/**
+ * The search index: what the search reads that the page does not already hold, as the plugin builds it for each group of
+ * story files and docs pages, and the shell loads on the first search.
+ *
+ * @remarks
+ * The names, keywords and stories are in the tree the sidebar draws, so the index leaves them out and holds only what
+ * would otherwise take opening every component: the props, the descriptions and the text of the documentation. It
+ * crosses from the plugin to the page as data, so it is checked on arrival (`isSearchIndex`). Pure.
+ *
+ * @module
+ */
+/** Whether a value is a plain object. */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Whether a value is left out or a text. */
+const isOptionalText = (value) => value === undefined || typeof value === "string";
+/** Whether a value is a stretch of documentation. */
+const isSection = (value) => isRecord(value) &&
+    typeof value["text"] === "string" &&
+    isOptionalText(value["anchor"]) &&
+    isOptionalText(value["heading"]);
+/** Whether a value is left out or a list of stretches of documentation. */
+const isOptionalSections = (value) => value === undefined || (Array.isArray(value) && value.every(isSection));
+/** Whether a value is a prop of a component. */
+const isProp = (value) => isRecord(value) &&
+    typeof value["name"] === "string" &&
+    typeof value["text"] === "string" &&
+    isOptionalText(value["part"]) &&
+    (value["isEvent"] === undefined || typeof value["isEvent"] === "boolean");
+/** Whether a value is what the search reads of a component. */
+const isComponent = (value) => isRecord(value) &&
+    isOptionalText(value["lead"]) &&
+    isOptionalSections(value["sections"]) &&
+    (value["props"] === undefined || (Array.isArray(value["props"]) && value["props"].every(isProp)));
+/**
+ * Whether a value is a group's index: what its loader gives is unchecked data.
+ *
+ * @param value - what the loader gave.
+ */
+export const isSearchIndex = (value) => isRecord(value) &&
+    (value["components"] === undefined ||
+        (isRecord(value["components"]) && Object.values(value["components"]).every(isComponent))) &&
+    (value["pages"] === undefined ||
+        (isRecord(value["pages"]) && Object.values(value["pages"]).every(isOptionalSections))) &&
+    (value["problems"] === undefined ||
+        (Array.isArray(value["problems"]) && value["problems"].every((problem) => typeof problem === "string")));
+/**
+ * Several groups' indexes as one: the keys are unique across a source's groups.
+ *
+ * @param indexes - the indexes.
+ */
+export const mergedSearchIndex = (indexes) => ({
+    components: Object.assign({}, ...indexes.map((index) => index.components)),
+    pages: Object.assign({}, ...indexes.map((index) => index.pages)),
+    problems: indexes.flatMap((index) => index.problems ?? [])
+});

package/dist/src/searchMarks.d.ts

@@ -0,0 +1,29 @@
+/** A piece of a text, marked when it matched. */
+export type MarkedText = {
+    /** The text. */
+    readonly text: string;
+    /** Whether it is what was searched for. */
+    readonly isMatch: boolean;
+};
+/** What was searched for, as the marks read it. */
+export type MarkedQuery = {
+    /** Its words. */
+    readonly words: readonly string[];
+    /** Its words as one text, when there are several (`foldedText`). */
+    readonly phrase: string | undefined;
+};
+/**
+ * A short text with what matched marked.
+ *
+ * @param text - the text.
+ * @param query - what was searched for.
+ */
+export declare const markedText: (text: string, query: MarkedQuery) => readonly MarkedText[];
+/**
+ * The part of a text worth showing, with what matched marked: around the matches that show most of the query, cut
+ * between words; the text's start when nothing in it matched.
+ *
+ * @param text - the text.
+ * @param query - what was searched for.
+ */
+export declare const snippetOf: (text: string, query: MarkedQuery) => readonly MarkedText[];