forgebook 0.1.8 → 0.2.0

package/dist/src/vite/figmaLink.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A design's link, as a story's `parameters.design.figma` writes it: read and checked once, by the index, then trusted
+ * by the shell, the tools and the catalogue's docs alike.
+ *
+ * @remarks
+ * A link is anything a story file writes, and the Design tab frames it, so it is taken apart rather than passed on:
+ * only `https` on Figma's own hosts is accepted, and the embed's address is built from the parts read here
+ * (`@forgebook/plugin-figma`). Figma's embed takes the kinds in `FILE_KINDS` only. Checking a story's link while
+ * indexing keeps the checker out of the shell's and the frame's first load: they read the index's link as it is. A docs
+ * page's `figma` fence is checked in the page, by the plugin's block, which loads only where a page draws one; this
+ * module imports nothing of Node for that reason (`forgebook/figma-link`).
+ *
+ * @module
+ */
+import type { FigmaLink } from "@forgebook/story-format/source";
+/**
+ * Reads a design's link.
+ *
+ * @remarks
+ * The link kept is rebuilt from the parts checked: the rest of what a story wrote (a tracking parameter, a path past the
+ * file's name, a fragment) would otherwise reach the page, the agents and `CATALOG.md` unchecked.
+ *
+ * @param text - the link, as a story writes it.
+ * @returns the link, or a message saying why it is not one.
+ */
+export declare const figmaLink: (text: string) => FigmaLink | string;

package/dist/src/vite/figmaLink.js

@@ -0,0 +1,92 @@
+/** The hosts a design's link may name; `embed.figma.com` is what a link copied from an embed code names. */
+const FIGMA_HOSTS = new Set(["figma.com", "www.figma.com", "embed.figma.com"]);
+/** The file kinds by the first segment of a link's path; `file` is the older name of `design`. */
+const FILE_KINDS = new Map([
+    ["design", "design"],
+    ["file", "design"],
+    ["proto", "proto"],
+    ["board", "board"],
+    ["slides", "slides"],
+    ["deck", "deck"]
+]);
+/** A file's or a branch's key, as Figma writes them. */
+const KEY = /^[A-Za-z0-9]+$/;
+/** A node's id, in a link (`12-34`, `I12-34;56-78`) or in Figma's REST API (`12:34`). */
+const NODE_ID = /^[A-Za-z]?\d+[-:]\d+(;\d+[-:]\d+)*$/;
+/** The most of a refused link a message repeats. */
+const MAX_QUOTED = 120;
+/**
+ * A refused link as a message shows it: on one line, shortened, since the message reaches terminals and agents.
+ *
+ * @param text - the link, as a story writes it.
+ */
+const quoted = (text) => JSON.stringify(text.slice(0, MAX_QUOTED));
+/**
+ * The node a link's `node-id` names, or why it cannot be one.
+ *
+ * @param url - the link.
+ * @returns the node as a link writes it; `undefined` when the link names none; an `Error` when it is malformed.
+ */
+const nodeIdOf = (url) => {
+    const [written, ...others] = url.searchParams.getAll("node-id");
+    if (written === undefined)
+        return undefined;
+    return NODE_ID.test(written) && others.length === 0
+        ? written
+        : new Error("its `node-id` is not one Figma node");
+};
+/**
+ * The key of the branch a link's path names, or why it cannot be one.
+ *
+ * @param third - the path's third segment.
+ * @param branchKey - the path's fourth segment.
+ * @returns the key; `undefined` for a link to no branch; an `Error` when the key is malformed, since the design shown
+ * would be the main file's and not the one linked to.
+ */
+const branchKeyOf = (third, branchKey) => {
+    if (third !== "branch")
+        return undefined;
+    return KEY.test(branchKey) ? branchKey : new Error("its branch is not a Figma key");
+};
+/**
+ * Reads a design's link.
+ *
+ * @remarks
+ * The link kept is rebuilt from the parts checked: the rest of what a story wrote (a tracking parameter, a path past the
+ * file's name, a fragment) would otherwise reach the page, the agents and `CATALOG.md` unchecked.
+ *
+ * @param text - the link, as a story writes it.
+ * @returns the link, or a message saying why it is not one.
+ */
+export const figmaLink = (text) => {
+    if (!URL.canParse(text))
+        return `${quoted(text)} is not an address`;
+    const url = new URL(text);
+    // a user name or a port would make the address read as Figma's while it could reach something else
+    const isFigma = url.protocol === "https:" &&
+        FIGMA_HOSTS.has(url.hostname) &&
+        url.port === "" &&
+        url.username === "" &&
+        url.password === "";
+    if (!isFigma)
+        return `${quoted(text)} is not a link to figma.com`;
+    const [first = "", fileKey = "", third, fourth = ""] = url.pathname.split("/").slice(1);
+    const kind = FILE_KINDS.get(first);
+    if (kind === undefined || !KEY.test(fileKey))
+        return `${quoted(text)} is not a link to a Figma file`;
+    const branchKey = branchKeyOf(third, fourth);
+    if (branchKey instanceof Error)
+        return `${quoted(text)}: ${branchKey.message}`;
+    const node = nodeIdOf(url);
+    if (node instanceof Error)
+        return `${quoted(text)}: ${node.message}`;
+    const branch = branchKey === undefined ? "" : `/branch/${branchKey}`;
+    const query = node === undefined ? "" : `?${new URLSearchParams({ "node-id": node }).toString()}`;
+    return {
+        url: `https://www.figma.com/${kind}/${fileKey}${branch}${query}`,
+        kind,
+        fileKey,
+        ...(branchKey === undefined ? {} : { branchKey }),
+        ...(node === undefined ? {} : { nodeId: node.replaceAll("-", ":") })
+    };
+};

package/dist/src/vite/findComponent.d.ts

@@ -0,0 +1,32 @@
+/** What the search reads of a component. */
+export type FindableComponent = {
+    /** Its id. */
+    readonly id: string;
+    /** Its whole title. */
+    readonly title: string;
+    /** The words its meta declares. */
+    readonly keywords: readonly string[];
+    /** Its stories' names and descriptions. */
+    readonly stories: readonly string[];
+};
+/** A component found. */
+export type FoundComponent = {
+    /** Its id. */
+    readonly id: string;
+    /** Its whole title. */
+    readonly title: 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[];
+};
+/**
+ * The components a query describes, best first.
+ *
+ * @param components - the catalogue's components.
+ * @param query - what is being looked for, in any words.
+ * @returns up to five; none when no word matches.
+ */
+export declare const findComponents: (components: readonly FindableComponent[], query: string) => FoundComponent[];

package/dist/src/vite/findComponent.js

@@ -0,0 +1,52 @@
+/**
+ * Finding a component by intent: the words a designer or an agent would use, not the name in the code.
+ *
+ * @remarks
+ * Pure, and with no model: a lexical ranking is instant, works offline and gives the same answer twice, and an index of a
+ * few hundred components is small enough for it. A component's name counts most, then the words its author declared
+ * (`keywords` in the meta, the way to say "radio tile group" of `OptionCards`), then its title and its stories' text. A
+ * short list of synonyms bridges the words designers and code use for the same thing (`searchMatch.ts`, which the
+ * catalogue's text search reads too). The answer says which words matched, so an agent can tell a strong result from a
+ * guess.
+ *
+ * @module
+ */
+import { wordsOf, worthOf } from "../searchMatch.js";
+/** How many components an answer gives. */
+const LIMIT = 5;
+/** A component's words. */
+const partsOf = (component) => ({
+    name: wordsOf(component.title.split("/").at(-1) ?? ""),
+    keyword: component.keywords.flatMap(wordsOf),
+    title: wordsOf(component.title),
+    story: component.stories.flatMap(wordsOf)
+});
+/**
+ * The components a query describes, best first.
+ *
+ * @param components - the catalogue's components.
+ * @param query - what is being looked for, in any words.
+ * @returns up to five; none when no word matches.
+ */
+export const findComponents = (components, query) => {
+    const words = wordsOf(query);
+    return components
+        .flatMap((component) => {
+        const parts = partsOf(component);
+        const scores = words.map((word) => ({ word, score: worthOf(parts, word) }));
+        const score = scores.reduce((sum, each) => sum + each.score, 0);
+        if (score === 0)
+            return [];
+        return [
+            {
+                id: component.id,
+                title: component.title,
+                score,
+                matched: scores.filter((each) => each.score > 0).map((each) => each.word),
+                missed: scores.filter((each) => each.score === 0).map((each) => each.word)
+            }
+        ];
+    })
+        .toSorted((first, second) => second.score - first.score)
+        .slice(0, LIMIT);
+};

package/dist/src/vite/findRoute.d.ts

@@ -0,0 +1,14 @@
+import type { IndexedComponent } from "./agentIndex.ts";
+import { type AgentAnswer, type RouteContext } from "./agentRoutes.ts";
+/**
+ * Every component as a search reads it, with what its answer carries, for a catalogue's index.
+ *
+ * @param context - what the routes read.
+ */
+export declare const indexedComponents: ({ tree, loaded }: RouteContext) => Promise<readonly IndexedComponent[]>;
+/**
+ * The components a query describes, with their guidance and the links of their first story.
+ *
+ * @param context - what the routes read.
+ */
+export declare const findAnswer: ({ tree, params, pages, view, loaded }: RouteContext) => Promise<AgentAnswer>;

package/dist/src/vite/findRoute.js

@@ -0,0 +1,62 @@
+import { isComponentDocs } from "../componentDocs.js";
+import { sourceFiles } from "../sourceFiles.js";
+import { storyLinks } from "./agentApi.js";
+import { settled } from "./agentRoutes.js";
+import { findComponents } from "./findComponent.js";
+/** Every component of the tree, with its source. */
+const treeComponents = (tree) => tree.sources.flatMap((source) => source.families.flatMap((family) => family.groups.flatMap((group) => group.components.map((component) => ({ source, component })))));
+/** What a component's docs say of when to use it; none when they cannot be read, which never loses the result. */
+const guidanceOfComponent = async (source, file) => {
+    if (source === undefined)
+        return undefined;
+    const loaded = await settled(sourceFiles(source).docs[file]);
+    const value = "value" in loaded ? loaded.value : undefined;
+    return isComponentDocs(value) ? value.guidance : undefined;
+};
+/** A component of the tree as the search reads it. */
+const findableOf = (component) => ({
+    id: component.id,
+    title: component.title,
+    keywords: component.keywords,
+    stories: component.stories.map((story) => `${story.name} ${story.description ?? ""}`)
+});
+/**
+ * Every component as a search reads it, with what its answer carries, for a catalogue's index.
+ *
+ * @param context - what the routes read.
+ */
+export const indexedComponents = ({ tree, loaded }) => Promise.all(treeComponents(tree).map(async ({ source, component }) => {
+    const loadedSource = loaded.sources.find((each) => each.id === source.id);
+    const guidance = await guidanceOfComponent(loadedSource, component.file);
+    return {
+        ...findableOf(component),
+        story: component.stories[0]?.id,
+        ...(guidance === undefined ? {} : { guidance })
+    };
+}));
+/**
+ * The components a query describes, with their guidance and the links of their first story.
+ *
+ * @param context - what the routes read.
+ */
+export const findAnswer = async ({ tree, params, pages, view, loaded }) => {
+    const query = params.get("query") ?? "";
+    if (query.trim() === "")
+        return { status: 400, body: { error: "No words to look for" } };
+    const located = treeComponents(tree);
+    const findable = located.map(({ component }) => findableOf(component));
+    const components = await Promise.all(findComponents(findable, query).map(async (found) => {
+        const place = located.find(({ component }) => component.id === found.id);
+        const story = place?.component.stories[0]?.id;
+        const source = loaded.sources.find((each) => each.id === place?.source.id);
+        const guidance = place === undefined ? undefined : await guidanceOfComponent(source, place.component.file);
+        return {
+            ...found,
+            story,
+            links: story === undefined ? undefined : storyLinks(pages, story, view),
+            ...(guidance === undefined ? {} : { guidance })
+        };
+    }));
+    const body = { schema: 1, query, components };
+    return { status: 200, body };
+};

package/dist/src/vite/forcedStates.d.ts

@@ -28,4 +28,3 @@ export declare const forcedSelector: (selector: Selector) => Selector;
  * simulation's (`touchMedia.ts`): the media rules that ask about the pointer follow the simulated touch.
  */
 export declare const FORCED_STATES_VISITOR: Visitor<CustomAtRules>;
-//# sourceMappingURL=forcedStates.d.ts.map

package/dist/src/vite/forcedStates.js

@@ -73,4 +73,3 @@ export const FORCED_STATES_VISITOR = {
     Selector: forcedSelector,
     Rule: { media: touchMediaRules }
 };
-//# sourceMappingURL=forcedStates.js.map

package/dist/src/vite/forgebookPlugin.d.ts

@@ -1,4 +1,4 @@
-import type { Plugin } from "vite";
+import { type Plugin } from "vite";
 import type { FrameworkAdapter } from "./adapter.ts";
 import { type ResolvedConfig } from "./configFile.ts";
 /** The plugin's options. */
@@ -25,4 +25,3 @@ export type ForgebookPluginOptions = {
  * @returns the plugin, for the app's `plugins`.
  */
 export declare const forgebookPlugin: (options?: ForgebookPluginOptions) => Plugin;
-//# sourceMappingURL=forgebookPlugin.d.ts.map