forgebook 0.1.8 → 0.3.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/fileAccess.d.ts

@@ -0,0 +1,51 @@
+import { type ResolvedConfig, type ViteDevServer } from "vite";
+import type { IsFileKept } from "./storyFilesModule.ts";
+/**
+ * Whether Vite refuses a listed file whatever `server.fs.allow` says: `deny`, or a path it will not trust (a `:` in it).
+ * Vite offers no check of this step alone, so this asks its whole check with an `allow` that covers the file.
+ *
+ * @param config - the dev server's configuration.
+ * @param file - the file, absolute in Vite's form.
+ */
+export declare const isFileRefused: (config: ResolvedConfig, file: string) => boolean;
+/**
+ * Whether a dev server may read the file a query's id names. An id Vite resolved is normalised; one with a `..` came
+ * from an address unresolved, and Vite's check reads a path as written, so `/project/../secret` would pass for a file
+ * of `/project`.
+ *
+ * @param config - the dev server's configuration.
+ * @param id - the module's id, the file and then its query.
+ */
+export declare const isQueriedFileReadable: (config: ResolvedConfig, id: string) => boolean;
+/** What a plugin's dev server lets a client read: `devServerAccess` makes it. */
+export type DevServerAccess = {
+    /** Starts on a dev server; until then (and in a build, which has none) nothing is refused. */
+    readonly serve: (server: ViteDevServer) => void;
+    /**
+     * Whether a resolver's importer is a module, not the stand-in Vite gives an address asked for directly.
+     *
+     * @param importer - the importer the resolver was given.
+     */
+    readonly isModule: (importer: string | undefined) => importer is string;
+    /**
+     * Notes that a module imports a group, whose id is now served.
+     *
+     * @param id - the group module's id.
+     */
+    readonly noteImported: (id: string) => void;
+    /** Whether a file a group lists may be read; says so once when not, as nothing else would tell why it is missing. */
+    readonly isKept: IsFileKept;
+    /**
+     * Whether a module is answered with nothing: a group no module imported, or a file `server.fs` refuses. Asked of every
+     * id, since an address can name an id directly, past the plugin's `resolveId`.
+     *
+     * @param id - the module's id.
+     */
+    readonly isRefused: (id: string) => boolean;
+};
+/**
+ * What a plugin's dev server lets a client read.
+ *
+ * @param renew - renews modules Vite keeps: a group refused before its first import would otherwise stay empty.
+ */
+export declare const devServerAccess: (renew: (server: ViteDevServer, ids: Iterable<string>) => void) => DevServerAccess;

package/dist/src/vite/fileAccess.js

@@ -0,0 +1,109 @@
+/**
+ * What a dev server's plugin may read for a client, by Vite's own `server.fs` and by what the project imports: a
+ * plugin's answer never passes through Vite's check, so each read an address can name asks here first.
+ *
+ * @remarks
+ * Vite's rule is two steps. The first refuses a file whatever else holds (`server.fs.deny`, a path it will not trust).
+ * Past it, a file is served when `allow` covers it or a module of the project imports it. A group of story files or
+ * docs pages is what a module of the project imports, so it keeps to the first step alone: a catalogue's `../src` may be
+ * outside `allow`, and Vite serves its files all the same. A query names one file in the address, so it asks both steps:
+ * Vite has recorded the file by then if a module imports it.
+ *
+ * A group's id holds its patterns, so an id alone must never choose what is read: any address could name a folder to
+ * list and read, and the imports the group's module writes would make Vite serve every file listed, past `allow`.
+ *
+ * @module
+ */
+import { realpathSync } from "node:fs";
+import { join } from "node:path";
+import { isFileLoadingAllowed } from "vite";
+import { isGroupId } from "./pluginIds.js";
+import { CODE_QUERY, DOCS_PAGE_QUERY, DOCS_QUERY, HOME_QUERY, MARKDOWN_QUERY, PAGE_QUERY } from "./textQueries.js";
+import { VITE_PATHS } from "./vitePaths.js";
+/** The queries the plugin answers with a file's text, so each read keeps to what the dev server may serve. */
+const FILE_QUERIES = [
+    DOCS_QUERY,
+    CODE_QUERY,
+    PAGE_QUERY,
+    MARKDOWN_QUERY,
+    DOCS_PAGE_QUERY,
+    HOME_QUERY
+];
+/**
+ * A listed file's real path, in Vite's form. Vite refuses a Windows short name (`RUNNER~1`), which could dodge `deny`,
+ * and a system's temporary folder is often written with one: the long name lets the file be judged by what it is. So
+ * does a link's target, which is the file that would be read.
+ *
+ * @param file - the file, absolute.
+ */
+const realFile = (file) => {
+    try {
+        return VITE_PATHS.normalize(realpathSync.native(file));
+    }
+    catch {
+        return file;
+    }
+};
+/**
+ * Whether Vite refuses a listed file whatever `server.fs.allow` says: `deny`, or a path it will not trust (a `:` in it).
+ * Vite offers no check of this step alone, so this asks its whole check with an `allow` that covers the file.
+ *
+ * @param config - the dev server's configuration.
+ * @param file - the file, absolute in Vite's form.
+ */
+export const isFileRefused = (config, file) => {
+    const real = realFile(file);
+    const fs = { ...config.server.fs, allow: [VITE_PATHS.dirname(real)] };
+    return !isFileLoadingAllowed({ ...config, server: { ...config.server, fs } }, real);
+};
+/**
+ * Whether a dev server may read the file a query's id names. An id Vite resolved is normalised; one with a `..` came
+ * from an address unresolved, and Vite's check reads a path as written, so `/project/../secret` would pass for a file
+ * of `/project`.
+ *
+ * @param config - the dev server's configuration.
+ * @param id - the module's id, the file and then its query.
+ */
+export const isQueriedFileReadable = (config, id) => {
+    const file = id.slice(0, id.lastIndexOf("?"));
+    return VITE_PATHS.normalize(file) === file && isFileLoadingAllowed(config, file);
+};
+/**
+ * What a plugin's dev server lets a client read.
+ *
+ * @param renew - renews modules Vite keeps: a group refused before its first import would otherwise stay empty.
+ */
+export const devServerAccess = (renew) => {
+    let devServer;
+    let addressImporter;
+    const imported = new Set();
+    const refused = new Set();
+    return {
+        serve: (server) => {
+            devServer = server;
+            addressImporter = join(server.config.root, "index.html");
+        },
+        isModule: (importer) => importer !== undefined && importer !== addressImporter,
+        noteImported: (id) => {
+            imported.add(id);
+            if (refused.delete(id) && devServer !== undefined)
+                renew(devServer, [id]);
+        },
+        isKept: (file) => {
+            if (devServer === undefined || !isFileRefused(devServer.config, file))
+                return true;
+            devServer.config.logger.warnOnce(`Forgebook leaves out ${file}: Vite's server.fs refuses it`);
+            return false;
+        },
+        isRefused: (id) => {
+            if (devServer === undefined)
+                return false;
+            if (!isGroupId(id))
+                return (FILE_QUERIES.some((query) => id.endsWith(query)) && !isQueriedFileReadable(devServer.config, id));
+            if (imported.has(id))
+                return false;
+            refused.add(id);
+            return true;
+        }
+    };
+};

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

@@ -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