@avocadostudio-ai/shared 0.3.2 → 0.4.0

package/dist/index.d.ts

@@ -1,11 +1,14 @@
 export { EDITOR_PROTOCOL_VERSION } from "./protocol.ts";
 export { getConfiguredDraftSecret, getSafeInternalRedirectPath, validateDraftSecret, type DraftSecretValidationResult } from "./draft-mode.ts";
 export type { FieldDiffKind, FieldDiff, BlockDiffStatus, BlockDiff, PageDiffStatus, PageDiff, PublishDiff, SiteConfigFieldDiff, SiteConfigDiff, } from "./publish-diff.ts";
-export { isImagePath, toAltPath, setPropAtPath } from "./editable-path.ts";
+export { isImagePath, toAltPath, isAltPath, toImagePath, setPropAtPath } from "./editable-path.ts";
+export { extractMarkedBlocks, editableCoverage, formatEditableCoverage } from "./editable-coverage.ts";
+export type { MarkedBlock, BlockCoverageGap, EditableCoverage } from "./editable-coverage.ts";
+export { parseLink, resolveLink, normalizeLinkPath, isKnownRoute, internalPathForUrl, rankLinkTargets, rankFileTargets, suggestLinkTargets, scoreLinkCandidate, suggestLinkTarget, newTabKeyFor, linkAttrs, isFilePath, knownFileExtensions, linksInRichText, type LinkKind, type ParsedLink, type ResolvedLink, type LinkPageOption, type LinkFileOption, type LinkSuggestions, } from "./links.ts";
 export { parseInline, parseRichText, parseRichTextBlocks, normalizeRichTextBody, resolveRichTextHeadingLevel, clampMarkdownHeadings, unescapeMarkdownText, isRichTextDoc, fromMarkdown, toMarkdown, mergeRichTextDoc, NODE, MARK, type InlineToken, type RichTextBlock, type RichTextList, type RichTextListItem, type RichTextDoc, type RichTextNode, type RichTextMark } from "@avocadostudio-ai/richtext";
 export { blockDefinitionSchema, blockManifestSchema, buildBlockManifest, jsonSchemaLikeSchema, validateByJsonSchemaLike, findManifestSchemaIssue, type ManifestSchemaIssue, validateManifestDefaultProps, deriveFieldMetaFromSchema, resolveManifestFieldMeta, isProseMirrorDocSchema, type BlockDefinition, type BlockManifest } from "./block-manifest.ts";
 export { z } from "zod";
-export { type FieldKind, type ImageSpec, type FieldMeta, type ListFieldMeta, type BlockMeta, type BlockType, type BlockInstance, type BlockRegistration, IMAGE_PLACEHOLDER, isImagePlaceholder, registerBlock, resetListFieldWarnings, getBlockMeta, getAllBlockMeta, getImageFields, getListImageFields, isFieldInlineEditable, getImageSpec, isChrome, getChromeTypes, blockSchemas, allowedBlockTypes, declareBlockCatalogue, getBlockCatalogue, isInBlockCatalogue, catalogueBlockTypes, undeclaredBlockTypes, getPropDisplayName, defaultListItemForBlock, blockInstanceSchema, blockInstanceSchemaLenient, validateBlockProps, getBlockJsonSchema, } from "./blocks/_registry.ts";
+export { type FieldKind, type ImageSpec, type FieldMeta, type ListFieldMeta, type BlockMeta, type BlockType, type BlockInstance, type BlockRegistration, IMAGE_PLACEHOLDER, isImagePlaceholder, registerBlock, resetListFieldWarnings, getBlockMeta, getAllBlockMeta, blockAcceptsProp, blockListItemAcceptsKey, getImageFields, getListImageFields, getMediaFields, isFieldInlineEditable, getImageSpec, isChrome, getChromeTypes, blockSchemas, allowedBlockTypes, declareBlockCatalogue, getBlockCatalogue, isInBlockCatalogue, catalogueBlockTypes, undeclaredBlockTypes, getPropDisplayName, defaultListItemForBlock, blockInstanceSchema, blockInstanceSchemaLenient, validateBlockProps, getBlockJsonSchema, } from "./blocks/_registry.ts";
 export { defaultPropsForType, declaredDefaultPropsForType, resolveHeadingTag, resolveItemHeadingTag, DEFAULT_HEADING_LEVELS, } from "./blocks/index.ts";
 export { blockTypeToCamel, camelToBlockType, blockTypeToLower, lowerToBlockType, } from "./block-names.ts";
 export { makeAddBlock, generateBlockId, makeAddItem, generateItemId, ensureItemIds, type AddBlockOp, type MakeAddBlockOptions, type AddItemOp, type MakeAddItemOptions, } from "./ops/builders.ts";

package/dist/index.js

@@ -1,6 +1,8 @@
 export { EDITOR_PROTOCOL_VERSION } from "./protocol.js";
 export { getConfiguredDraftSecret, getSafeInternalRedirectPath, validateDraftSecret } from "./draft-mode.js";
-export { isImagePath, toAltPath, setPropAtPath } from "./editable-path.js";
+export { isImagePath, toAltPath, isAltPath, toImagePath, setPropAtPath } from "./editable-path.js";
+export { extractMarkedBlocks, editableCoverage, formatEditableCoverage } from "./editable-coverage.js";
+export { parseLink, resolveLink, normalizeLinkPath, isKnownRoute, internalPathForUrl, rankLinkTargets, rankFileTargets, suggestLinkTargets, scoreLinkCandidate, suggestLinkTarget, newTabKeyFor, linkAttrs, isFilePath, knownFileExtensions, linksInRichText, } from "./links.js";
 /*
  * The rich-text grammar lives in `@avocadostudio-ai/richtext`, which owns the
  * parser and every CMS converter and has no dependencies of its own. It is
@@ -33,7 +35,7 @@ export {
 // Constants & helpers
 IMAGE_PLACEHOLDER, isImagePlaceholder, 
 // Registry functions
-registerBlock, resetListFieldWarnings, getBlockMeta, getAllBlockMeta, getImageFields, getListImageFields, isFieldInlineEditable, getImageSpec, isChrome, getChromeTypes, 
+registerBlock, resetListFieldWarnings, getBlockMeta, getAllBlockMeta, blockAcceptsProp, blockListItemAcceptsKey, getImageFields, getListImageFields, getMediaFields, isFieldInlineEditable, getImageSpec, isChrome, getChromeTypes, 
 // Backwards-compatible exports
 blockSchemas, allowedBlockTypes, 
 // The catalogue a site actually renders — see `declareBlockCatalogue`

package/dist/links.d.ts

@@ -0,0 +1,243 @@
+/**
+ * What a link field's string actually means.
+ *
+ * A link is stored as a plain string — `/pricing`, `https://example.com`,
+ * `mailto:hi@example.com` — and three places need to agree on how to read it:
+ * the editor's link control (which icon, which label, which warning), the
+ * `seo.internal-link-dead` check (is this route real?), and the rename rewriter
+ * (is this string a route at all?). Before this module each answered the
+ * question with its own inline `startsWith("/")`, and they did not agree: the
+ * rename rewriter matched on prop *names* containing "href", so a link stored
+ * under `url` or inside Footer's `label|url` text went stale on every rename.
+ *
+ * Nothing here validates in the blocking sense. A path this module cannot
+ * resolve is still a legitimate link — on a CMS-backed site Avocado sees only
+ * the pages it was handed, and a route can exist in Next, in the CMS, or behind
+ * a rewrite and be invisible from here. `resolveLink` reports what it knows; it
+ * never decides what the editor may type.
+ */
+/** How a link string addresses its target. */
+export type LinkKind = "empty" | "page" | "file" | "external" | "email" | "phone" | "anchor";
+/** Does this route-shaped path name a document rather than a page? */
+export declare function isFilePath(path: string): boolean;
+/**
+ * The file extensions this module recognises, for a caller that has to describe
+ * them — an upload control's `accept`, a picker's filter, a docs page.
+ */
+export declare function knownFileExtensions(): string[];
+/** A link string, classified. */
+export type ParsedLink = {
+    kind: LinkKind;
+    /** The original string, untouched. */
+    raw: string;
+    /**
+     * The route, for `kind: "page"` — path only, with `?query` and `#fragment`
+     * stripped. This is what `resolveLink` matches against the site's slugs.
+     */
+    path?: string;
+    /** The `?a=b#c` tail of a page link, preserved so a rewrite can restore it. */
+    suffix?: string;
+    /** Host for `external`, address for `email`, number for `phone`, id for `anchor`. */
+    target?: string;
+};
+/** A page the editor can offer as a link target. */
+export type LinkPageOption = {
+    slug: string;
+    /** The URL, when the site says it differs from the slug (locale prefixes). */
+    path?: string;
+    title?: string;
+};
+/** Classify a link string. Never throws; anything unrecognised parses as `page`-ish text. */
+export declare function parseLink(value: unknown): ParsedLink;
+/**
+ * Give a route its leading slash and drop a trailing one.
+ *
+ * `pricing`, `/pricing`, `/pricing/` are the same page. The editor accepts all
+ * three and stores the middle one. The homepage keeps its lone slash.
+ */
+export declare function normalizeLinkPath(path: string): string;
+/**
+ * Does this route exist among the site's known pages?
+ *
+ * Compares on the path alone — a link may legitimately carry a query or a
+ * fragment, and neither changes which page it points at — and accepts a
+ * trailing slash on either side. This is the matcher `seo.internal-link-dead`
+ * uses, extracted so the inline field warning and the checks panel cannot
+ * disagree about what "dead" means.
+ */
+export declare function isKnownRoute(path: string, knownSlugs: Iterable<string>): boolean;
+/**
+ * A document the site can link to, as the editor needs to know it.
+ *
+ * `path` is what goes in the link. Everything else is for showing it to a
+ * person, and every field but `path` is optional because a site that answers
+ * this question from a directory listing has only the path.
+ */
+export type LinkFileOption = {
+    /** The URL to link to — `/downloads/menu-de.pdf`. */
+    path: string;
+    /** What to call it in a picker. Defaults to the filename. */
+    name?: string;
+    /** MIME type, when the store knows it. */
+    contentType?: string;
+    /** Bytes, when the store knows it — a picker shows it, nothing decides on it. */
+    size?: number;
+};
+/** A parsed link plus what the site knows about its target. */
+export type ResolvedLink = ParsedLink & {
+    /** The matching page, when `kind` is `page` and the route is known. */
+    page?: LinkPageOption;
+    /** The matching document, when `kind` is `file` and the asset list has it. */
+    file?: LinkFileOption;
+    /**
+     * True for a link whose target matches nothing the site knows about.
+     *
+     * For a `page` this is decided from the slug list, which is always present.
+     * For a `file` it is decided from the asset list, which is *not* — a site
+     * that cannot enumerate its documents passes none, and then `missing` stays
+     * undefined rather than becoming `true`. "We did not check" and "it is not
+     * there" have to stay distinguishable, or every site without an asset store
+     * would report all of its own documents as broken.
+     */
+    missing?: boolean;
+};
+/**
+ * Classify a link *and* look up its target. Pages may be keyed by `slug` or by
+ * `path` (they differ on locale-prefixed sites — see
+ * `docs/ideas/page-identity-punch-list.md`), so both are matched.
+ *
+ * `files` is optional and its absence is meaningful — see `missing` above.
+ */
+export declare function resolveLink(value: unknown, pages?: readonly LinkPageOption[], files?: readonly LinkFileOption[]): ResolvedLink;
+/**
+ * How well a page answers what was typed, from 0 (nothing in common) to 1.
+ *
+ * The balanced mean of precision and recall over shared words. Balanced because
+ * both halves are wrong alone: precision by itself ranks a sprawling page that
+ * happens to contain the word above the page actually named for it, and recall
+ * by itself ranks a one-word slug above every longer match.
+ *
+ * Pass the site's pages as `corpus` to weight words by how distinctive they are
+ * (see `tokenWeights`); without it every word counts the same.
+ */
+export declare function scoreLinkCandidate(query: string, page: LinkPageOption, corpus?: readonly LinkPageOption[]): number;
+/**
+ * Known pages ranked by how well they answer `query`, best first.
+ *
+ * Held to the same floor as `suggestLinkTarget`, which it did not used to be:
+ * anything sharing a single token came back, so on a tri-lingual site every
+ * `/fr/*` page answered every French-flavoured query. Typing a document path
+ * into the link picker listed `/fr/`, `/fr/faq/` and `/fr/evenements/` — six
+ * rows of pages, each one click away from replacing a working PDF link with a
+ * link to the FAQ. A near-miss still ranks well above the floor; what the floor
+ * removes is the coincidence.
+ */
+export declare function rankLinkTargets(query: string, pages: readonly LinkPageOption[]): LinkPageOption[];
+/**
+ * Known documents ranked by how well they answer `query`, best first.
+ *
+ * The same scorer as pages, and the corpus weighting is what makes it work
+ * here: every document on a site shares its directory and its extension, so
+ * `downloads` and `pdf` identify nothing and are weighted to nearly nothing,
+ * while the part of the filename someone got wrong is what decides the order.
+ *
+ * This is the half a substring filter cannot do. `AadventureArenaBerm` is a
+ * real filename on a real site, typo included; a person typing it from memory
+ * gets one character wrong and a substring match returns nothing at all —
+ * which reads exactly like "this site has no such document".
+ */
+export declare function rankFileTargets(query: string, files: readonly LinkFileOption[]): LinkFileOption[];
+/** What a link picker should offer for what has been typed so far. */
+export type LinkSuggestions = {
+    pages: LinkPageOption[];
+    files: LinkFileOption[];
+};
+/**
+ * The pages and documents to offer for a partly-typed link.
+ *
+ * Two surfaces ask this question — the property panel's link field and the
+ * prose editor's link popover — and they answered it with their own inline
+ * copies of "substring, else rank". The copies disagreed, and both made the
+ * same mistake: they ranked *pages* for a query the parser had already
+ * classified as a document. A screenshot of the result is why this function
+ * exists — `/downloads/…-Gruppen-FR.pdf` typed in, six pages offered, not one
+ * of the site's fifteen PDFs among them.
+ *
+ * So the kind decides which list is offered at all:
+ *
+ * - a document path offers documents, never pages;
+ * - a route offers pages, and any document whose path literally contains what
+ *   was typed (`menu` should still find the menu PDFs);
+ * - `mailto:`, `tel:`, `#anchor` and `https://` offer neither — there is
+ *   nothing on this site they could mean, and the caller's empty state can say
+ *   so instead.
+ *
+ * Within a kind, a literal substring is what a person typing into a box
+ * expects, and ranking is the fallback for when nothing matches literally.
+ */
+export declare function suggestLinkTargets(query: string, options?: {
+    pages?: readonly LinkPageOption[];
+    files?: readonly LinkFileOption[];
+    limit?: number;
+    /**
+     * With an empty box, list the site's first documents alongside its pages.
+     * The prose picker wants that — it is how an editor discovers the site has
+     * documents at all. The link *field* does not: a document shelf under every
+     * link field would bury the pages, which is what a link usually wants.
+     */
+    browseFiles?: boolean;
+}): LinkSuggestions;
+/**
+ * The page a dead internal link probably meant.
+ *
+ * `/avocado-sustainability` on a site that has `/sustainability` is a typo, a
+ * stale link, or a slug someone renamed by hand — and the site already holds
+ * everything needed to say so. Returns undefined when nothing scores well
+ * enough, or when the link already resolves; the caller offers what comes back,
+ * and never applies it on the editor's behalf.
+ */
+export declare function suggestLinkTarget(value: unknown, pages: readonly LinkPageOption[]): LinkPageOption | undefined;
+/**
+ * The absolute URL a viewer would copy out of the address bar, turned back into
+ * an internal route — when it belongs to this site.
+ *
+ * Pasting the address bar is how people actually get a URL, and an absolute one
+ * survives right up until the site moves domain. Returns undefined when the
+ * origin is someone else's, so the caller leaves the link alone.
+ */
+export declare function internalPathForUrl(value: string, siteOrigin: string | undefined): string | undefined;
+/**
+ * The prop holding the "open in new tab" flag for a link prop, by convention.
+ *
+ * `ctaHref` → `ctaNewTab`, `secondaryCtaHref` → `secondaryCtaNewTab`,
+ * `href` → `newTab`. The same shape as the `image`/`imageAlt` pairing the
+ * property panel already resolves by name, so a block declares two props and
+ * the editor renders one control.
+ */
+export declare function newTabKeyFor(linkKey: string): string;
+/** Anchor attributes for a link, given its stored value and new-tab flag. */
+export declare function linkAttrs(href: unknown, newTab?: unknown): {
+    href: string;
+    target?: string;
+    rel?: string;
+};
+/**
+ * Every href inside a richtext value.
+ *
+ * A link is not only a `link`-kind prop. Most of the links on a real page are
+ * written *into* prose — `[Menükarte](/downloads/menu-de.pdf)` — and every
+ * link-aware surface we have was walking declared fields only. So the four
+ * menu-PDF links on a live site's Bistro section were not checked, not
+ * rewritten on rename, and not reported; the one linking to a filename with a
+ * typo in it had been wrong since August with nothing able to notice.
+ *
+ * Three shapes, because a richtext value is three things depending on where it
+ * came from: markdown (a site that projects its CMS prose to markdown), a
+ * ProseMirror document (the editor's own format), and raw HTML (a block with a
+ * loose schema). Walking all three costs one function and means a caller never
+ * has to know which it was handed.
+ *
+ * Returns hrefs in document order, duplicates included — a caller that reports
+ * findings wants one per occurrence, and a caller that wants a set can make one.
+ */
+export declare function linksInRichText(value: unknown): string[];