beez-ui 0.6.2 → 0.8.0

package/dist/lib/rich-text/link-markdown-constants.js

@@ -0,0 +1,458 @@
+/**
+* Shared constants for the rich-text link layer.
+*
+* These values back both the read-only renderer (`RichTextContent`) and the
+* rich link editor (`RichLinkEditor` / `useRichLinkEditor`). They are framework
+* safe and free of business rules, so they live under `lib` and can be reused by
+* any feature that needs autolinking plus `[text](url)` markdown support.
+*/
+/** URL protocols accepted when normalizing a markdown link target. */
+export const LINK_MARKDOWN_ALLOWED_PROTOCOL = {
+	http: "http:",
+	https: "https:"
+};
+/** Protocol prepended to bare domains that lack an explicit scheme. */
+export const LINK_PROTOCOL_PREFIX = { default: "https://" };
+/** Tokens used to assemble and recognize `[text](url)` markdown links. */
+export const LINK_MARKDOWN_FORMAT = {
+	closeLabel: "]",
+	closeUrl: ")",
+	openLabel: "[",
+	openUrl: "](",
+	suppressedUrl: "#"
+};
+/**
+* Parentheses that the `[text](url)` markdown URL group cannot represent
+* unescaped, paired with their percent-encoded equivalents. The URL group only
+* accepts balanced single-level `(...)` pairs, so any other paren must be
+* encoded when serializing a link target; browsers decode `%28`/`%29` back to
+* the literal character when the link is opened.
+*/
+export const LINK_MARKDOWN_URL_PAREN = {
+	close: ")",
+	encodedClose: "%29",
+	encodedOpen: "%28",
+	open: "("
+};
+/** Patterns matching characters that must be escaped inside link label text. */
+export const LINK_MARKDOWN_ESCAPE_PATTERN = {
+	backslash: /\\/g,
+	closeLabel: /\]/g,
+	lineBreak: /\n/g,
+	openLabel: /\[/g
+};
+/** Escape sequences paired with `LINK_MARKDOWN_ESCAPE_PATTERN`. */
+export const LINK_MARKDOWN_ESCAPE_VALUE = {
+	backslash: "\\",
+	escapedBackslash: "\\\\",
+	escapedCloseLabel: "\\]",
+	escapedLineBreak: "\\n",
+	escapedOpenLabel: "\\[",
+	lineBreakToken: "n"
+};
+/** Discriminant for the parsed rich-text segments (plain text vs. link). */
+export const RICH_TEXT_SEGMENT_TYPE = {
+	link: "link",
+	text: "text"
+};
+/** Whether an editor link is explicit (`[text](url)`) or a suppressed autolink. */
+export const RICH_LINK_KIND = {
+	explicit: "explicit",
+	suppressed: "suppressed"
+};
+/** Origin of a preview link segment: auto-detected URL vs. explicit link. */
+export const RICH_PREVIEW_LINK_SOURCE = {
+	automatic: "automatic",
+	explicit: "explicit"
+};
+/** Editing modes of the link popover. */
+export const RICH_LINK_POPOVER_MODE = {
+	actions: "actions",
+	edit: "edit"
+};
+/**
+* Regular expressions used to detect links in plain text.
+*
+* The URL character classes exclude both `)` and `]` so a URL wrapped in
+* brackets or parentheses (`[https://example.com/path]`) stops at the closing
+* delimiter instead of swallowing it into the link target. Balanced `(...)`
+* inside the URL is still matched through the dedicated paren-balancing group.
+*/
+export const LINK_PATTERN = {
+	bareDomain: /^(?:[a-zA-Z0-9-]+\.)+[a-zA-Z]{2,}[^\s<>)\]]*$/,
+	containsWhitespace: /\s/,
+	bareUrl: /(?:https?:\/\/[^\s<>)\]]*(?:\([^\s<>()]*\)[^\s<>)\]]*)*|(?:[a-zA-Z0-9-]+\.)+[a-zA-Z]{2,}[^\s<>)\]]*(?:\([^\s<>()]*\)[^\s<>)\]]*)*)/g,
+	hostBoundary: /[/?#:]/,
+	markdown: /\[((?:\\[\s\S]|[^\]\\])+)\]\(((?:[^()\s]+|\([^()\s]*\))+)\)/g,
+	protocolPrefix: /^https?:\/\//i,
+	trailingPunctuation: /[.,!?;:]+$/,
+	whitespace: /^\s+$/
+};
+/**
+* Public top-level domains recognized when auto-linking a scheme-less bare
+* domain found in prose. `new URL()` accepts any syntactically valid hostname,
+* so without this allowlist Spanish abbreviations like `EE.UU.` or
+* end-of-sentence transitions like `China.Por` would resolve to bogus hosts and
+* become clickable links. It covers the common gTLDs plus every assigned
+* two-letter ccTLD; unknown suffixes such as `uu` or `por` are intentionally
+* absent. This gates only the automatic detection path: explicit `http(s)://`
+* URLs and links the user pastes deliberately bypass it and stay permissive.
+*/
+export const KNOWN_TOP_LEVEL_DOMAINS = new Set([
+	"com",
+	"net",
+	"org",
+	"info",
+	"biz",
+	"name",
+	"pro",
+	"int",
+	"edu",
+	"gov",
+	"mil",
+	"app",
+	"dev",
+	"io",
+	"co",
+	"ai",
+	"xyz",
+	"online",
+	"site",
+	"tech",
+	"store",
+	"shop",
+	"blog",
+	"me",
+	"tv",
+	"cc",
+	"live",
+	"life",
+	"world",
+	"fun",
+	"space",
+	"website",
+	"page",
+	"web",
+	"link",
+	"click",
+	"news",
+	"media",
+	"studio",
+	"design",
+	"art",
+	"email",
+	"cloud",
+	"digital",
+	"network",
+	"agency",
+	"company",
+	"group",
+	"team",
+	"work",
+	"works",
+	"today",
+	"ltd",
+	"inc",
+	"llc",
+	"academy",
+	"school",
+	"courses",
+	"education",
+	"events",
+	"social",
+	"chat",
+	"video",
+	"photo",
+	"photos",
+	"games",
+	"game",
+	"finance",
+	"money",
+	"health",
+	"fit",
+	"run",
+	"travel",
+	"tours",
+	"global",
+	"international",
+	"solutions",
+	"systems",
+	"consulting",
+	"marketing",
+	"software",
+	"host",
+	"hosting",
+	"wiki",
+	"ac",
+	"ad",
+	"ae",
+	"af",
+	"ag",
+	"al",
+	"am",
+	"ao",
+	"aq",
+	"ar",
+	"as",
+	"at",
+	"au",
+	"aw",
+	"ax",
+	"az",
+	"ba",
+	"bb",
+	"bd",
+	"be",
+	"bf",
+	"bg",
+	"bh",
+	"bi",
+	"bj",
+	"bm",
+	"bn",
+	"bo",
+	"br",
+	"bs",
+	"bt",
+	"bw",
+	"by",
+	"bz",
+	"ca",
+	"cd",
+	"cf",
+	"cg",
+	"ch",
+	"ci",
+	"ck",
+	"cl",
+	"cm",
+	"cn",
+	"cr",
+	"cu",
+	"cv",
+	"cw",
+	"cx",
+	"cy",
+	"cz",
+	"de",
+	"dj",
+	"dk",
+	"dm",
+	"do",
+	"dz",
+	"ec",
+	"ee",
+	"eg",
+	"er",
+	"es",
+	"et",
+	"eu",
+	"fi",
+	"fj",
+	"fk",
+	"fm",
+	"fo",
+	"fr",
+	"ga",
+	"gd",
+	"ge",
+	"gf",
+	"gg",
+	"gh",
+	"gi",
+	"gl",
+	"gm",
+	"gn",
+	"gp",
+	"gq",
+	"gr",
+	"gs",
+	"gt",
+	"gu",
+	"gw",
+	"gy",
+	"hk",
+	"hm",
+	"hn",
+	"hr",
+	"ht",
+	"hu",
+	"id",
+	"ie",
+	"il",
+	"im",
+	"in",
+	"iq",
+	"ir",
+	"is",
+	"it",
+	"je",
+	"jm",
+	"jo",
+	"jp",
+	"ke",
+	"kg",
+	"kh",
+	"ki",
+	"km",
+	"kn",
+	"kp",
+	"kr",
+	"kw",
+	"ky",
+	"kz",
+	"la",
+	"lb",
+	"lc",
+	"li",
+	"lk",
+	"lr",
+	"ls",
+	"lt",
+	"lu",
+	"lv",
+	"ly",
+	"ma",
+	"mc",
+	"md",
+	"mg",
+	"mh",
+	"mk",
+	"ml",
+	"mm",
+	"mn",
+	"mo",
+	"mp",
+	"mq",
+	"mr",
+	"ms",
+	"mt",
+	"mu",
+	"mv",
+	"mw",
+	"mx",
+	"my",
+	"mz",
+	"na",
+	"nc",
+	"ne",
+	"nf",
+	"ng",
+	"ni",
+	"nl",
+	"no",
+	"np",
+	"nr",
+	"nu",
+	"nz",
+	"om",
+	"pa",
+	"pe",
+	"pf",
+	"pg",
+	"ph",
+	"pk",
+	"pl",
+	"pm",
+	"pn",
+	"pr",
+	"ps",
+	"pt",
+	"pw",
+	"py",
+	"qa",
+	"re",
+	"ro",
+	"rs",
+	"ru",
+	"rw",
+	"sa",
+	"sb",
+	"sc",
+	"sd",
+	"se",
+	"sg",
+	"sh",
+	"si",
+	"sk",
+	"sl",
+	"sm",
+	"sn",
+	"so",
+	"sr",
+	"ss",
+	"st",
+	"sv",
+	"sx",
+	"sy",
+	"sz",
+	"tc",
+	"td",
+	"tf",
+	"tg",
+	"th",
+	"tj",
+	"tk",
+	"tl",
+	"tm",
+	"tn",
+	"to",
+	"tr",
+	"tt",
+	"tw",
+	"tz",
+	"ua",
+	"ug",
+	"uk",
+	"us",
+	"uy",
+	"uz",
+	"va",
+	"vc",
+	"ve",
+	"vg",
+	"vi",
+	"vn",
+	"vu",
+	"wf",
+	"ws",
+	"ye",
+	"yt",
+	"za",
+	"zm",
+	"zw"
+]);
+/** Capture group indexes of `LINK_PATTERN.markdown`. */
+export const LINK_MARKDOWN_MATCH_GROUP = {
+	text: 1,
+	url: 2
+};
+/** Sentinel returned by the text diff when no change is found. */
+export const TEXT_DIFF_FALLBACK_INDEX = { notFound: -1 };
+/** Separator used to build a stable key for preview link segments. */
+export const PREVIEW_LINK_KEY_SEPARATOR = { value: ":" };
+/** Clipboard data type read on paste inside the editor. */
+export const RICH_TEXT_CLIPBOARD_DATA_TYPE = { plainText: "text/plain" };
+/** `InputEvent.inputType` values handled by the editor's `beforeInput`. */
+export const RICH_TEXT_EDITOR_INPUT_TYPE = {
+	deleteContentBackward: "deleteContentBackward",
+	deleteContentForward: "deleteContentForward",
+	insertLineBreak: "insertLineBreak",
+	insertParagraph: "insertParagraph",
+	insertText: "insertText"
+};
+/** Keyboard keys handled by the editor's `keydown`. */
+export const RICH_TEXT_EDITOR_KEY = {
+	backspace: "Backspace",
+	delete: "Delete",
+	enter: "Enter"
+};
+/** Direction of a word-wise deletion. */
+export const RICH_TEXT_EDITOR_WORD_DIRECTION = {
+	backward: "backward",
+	forward: "forward"
+};
+/** Length of a single editable character. */
+export const RICH_TEXT_EDITOR_KEY_LENGTH = { character: 1 };
+/** Literal text tokens used by the editor. */
+export const RICH_TEXT_EDITOR_TEXT = { lineBreak: "\n" };

package/dist/lib/rich-text/link-markdown-types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Shared types for the rich-text link layer.
+ */
+import type { RICH_LINK_KIND, RICH_PREVIEW_LINK_SOURCE, RICH_TEXT_SEGMENT_TYPE } from "./link-markdown-constants.js";
+/** A parsed piece of rendered content: either plain text or a link. */
+export type RichTextSegment = {
+    text: string;
+    type: typeof RICH_TEXT_SEGMENT_TYPE.text;
+} | {
+    text: string;
+    type: typeof RICH_TEXT_SEGMENT_TYPE.link;
+    url: string;
+};
+/**
+ * A link tracked by the editor over its plain-text content. Explicit links carry
+ * a target URL; suppressed links mark an auto-detected URL the author removed.
+ */
+export type RichLink = {
+    end: number;
+    id: string;
+    isSynced: boolean;
+    kind: typeof RICH_LINK_KIND.explicit;
+    start: number;
+    url: string;
+} | {
+    end: number;
+    id: string;
+    kind: typeof RICH_LINK_KIND.suppressed;
+    start: number;
+};
+/** A segment of the editor preview: plain text or an interactive link. */
+export type RichPreviewSegment = {
+    text: string;
+    type: typeof RICH_TEXT_SEGMENT_TYPE.text;
+} | {
+    end: number;
+    id?: string;
+    key: string;
+    source: typeof RICH_PREVIEW_LINK_SOURCE.automatic | typeof RICH_PREVIEW_LINK_SOURCE.explicit;
+    start: number;
+    text: string;
+    type: typeof RICH_TEXT_SEGMENT_TYPE.link;
+    url: string;
+};
+/** The link variant of a preview segment, used when editing a link. */
+export type ActiveRichPreviewLink = Extract<RichPreviewSegment, {
+    type: typeof RICH_TEXT_SEGMENT_TYPE.link;
+}>;
+/** A character offset range within the editor's plain-text content. */
+export type RichTextSelectionRange = {
+    end: number;
+    start: number;
+};

package/dist/lib/rich-text/link-markdown-types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/rich-text/link-markdown.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Pure helpers for the rich-text link layer: URL normalization, markdown
+ * link (de)serialization, plain-text autolink parsing, and editor link
+ * bookkeeping. None of these touch the DOM, so they are unit-testable in
+ * isolation and shared by the renderer, the editor hook, and persistence.
+ */
+import { RICH_PREVIEW_LINK_SOURCE, RICH_TEXT_EDITOR_WORD_DIRECTION } from "./link-markdown-constants.js";
+import type { RichLink, RichPreviewSegment, RichTextSegment, RichTextSelectionRange } from "./link-markdown-types.js";
+/**
+ * Normalizes a raw markdown URL into a safe absolute `http(s)` URL, or `null`
+ * when it is not a usable web link. Bare domains gain an `https://` prefix.
+ *
+ * A candidate that contains whitespace is returned as its parsed `href`, which
+ * percent-encodes those characters. The renderer's `LINK_PATTERN.markdown` URL
+ * group forbids whitespace, so persisting the raw candidate would serialize a
+ * `[text](url with space)` link that cannot be read back and renders as broken
+ * markdown. Whitespace-free candidates are returned verbatim to preserve their
+ * exact form (no trailing slash, stable synchronization checks).
+ *
+ * A scheme-less candidate that parses into userinfo (`john.doe@example.com`) is
+ * rejected: the `bareDomain` pattern allows `@` in its trailing class, so an
+ * email or literal slips through and prepending `https://` would yield
+ * `https://john.doe@example.com`, where the browser reads `john.doe` as
+ * credentials for `example.com`. That turns the value into a misleading
+ * outbound link, against the convention that email addresses are not linked.
+ * The check uses the parsed `username`/`password` rather than a naive `@` scan
+ * so a legitimate `@` past the authority (a path or query) still links.
+ */
+export declare function normalizeMarkdownUrl(rawUrl: string | null | undefined): string | null;
+/**
+ * Extracts the top-level domain (the last dot-separated label of the host) from
+ * a bare or scheme-prefixed candidate, lowercased, or `null` when the candidate
+ * has no host label past a dot. The host ends at the first path, query,
+ * fragment, or port boundary so a path segment is never mistaken for the TLD.
+ */
+export declare function getCandidateTopLevelDomain(candidate: string): string | null;
+/**
+ * Normalizes a candidate for the automatic detection path. Scheme-prefixed URLs
+ * are trusted and normalized as-is; a scheme-less bare domain is only accepted
+ * when its TLD is a recognized public suffix, so prose abbreviations such as
+ * `EE.UU.` or `China.Por` stay plain text instead of resolving to bogus hosts.
+ * Explicit paste-as-link flows keep using `normalizeMarkdownUrl` directly and
+ * stay permissive.
+ */
+export declare function normalizeAutolinkUrl(candidate: string): string | null;
+/** Strips the `http(s)://` prefix from a value for synchronization checks. */
+export declare function removeLinkProtocolPrefix(value: string): string;
+/** Whether a link's visible text matches its URL ignoring the protocol. */
+export declare function isLinkSynchronized(text: string, url: string): boolean;
+/** Returns the protocol prefix of a URL, defaulting to `https://`. */
+export declare function getLinkProtocolPrefix(url: string): string;
+/**
+ * Rebuilds the URL of a synchronized link after its visible text changed, so a
+ * link whose label is the URL keeps tracking the edited text.
+ */
+export declare function getSynchronizedLinkUrl(text: string, currentUrl: string): string | null;
+/** Whether the value contains only whitespace. */
+export declare function isWhitespaceOnly(value: string): boolean;
+/**
+ * Computes the range a word-wise deletion (Ctrl/Alt+Backspace/Delete) should
+ * remove from a collapsed caret, mirroring native word deletion.
+ */
+export declare function getWordDeletionRange(input: {
+    direction: typeof RICH_TEXT_EDITOR_WORD_DIRECTION.backward | typeof RICH_TEXT_EDITOR_WORD_DIRECTION.forward;
+    selectionRange: RichTextSelectionRange;
+    text: string;
+}): RichTextSelectionRange;
+/**
+ * Percent-encodes the parentheses a URL cannot keep literal inside a
+ * `[text](url)` target, so an explicit link whose URL contains an unmatched or
+ * nested `(`/`)` (for example `https://example.com/a)b`) serializes to markdown
+ * that `LINK_PATTERN.markdown` reads back as the same link instead of truncating
+ * the target at the stray paren and spilling the rest into plain text.
+ *
+ * The URL group only matches balanced single-level `(...)` pairs, so those are
+ * preserved verbatim (keeping links like `.../Foo_(bar)` intact); every other
+ * paren becomes `%28`/`%29`, which is decoded back to the literal character when
+ * the link is opened.
+ */
+export declare function escapeMarkdownLinkUrl(url: string): string;
+/** Builds a `[text](url)` markdown link, escaping the label and the URL. */
+export declare function buildMarkdownLinkFromSelection(text: string, url: string): string;
+/** Escapes characters that would break a markdown link label. */
+export declare function escapeMarkdownLinkText(text: string): string;
+/** Reverses `escapeMarkdownLinkText`, restoring line breaks and literals. */
+export declare function unescapeMarkdownLinkText(text: string): string;
+/** Builds a stable React key for a preview link segment. */
+export declare function buildPreviewLinkKey(segment: {
+    id?: string;
+    source: typeof RICH_PREVIEW_LINK_SOURCE.automatic | typeof RICH_PREVIEW_LINK_SOURCE.explicit;
+    start: number;
+    url: string;
+}): string;
+/** Creates a plain-text rendered segment. */
+export declare function createTextSegment(text: string): RichTextSegment;
+/** Creates a link rendered segment. */
+export declare function createLinkSegment(text: string, url: string): RichTextSegment;
+/** Creates a plain-text editor preview segment. */
+export declare function createTextPreviewSegment(text: string): RichPreviewSegment;
+/** Creates a link editor preview segment with a stable key. */
+export declare function createLinkPreviewSegment(input: {
+    end: number;
+    id?: string;
+    source: typeof RICH_PREVIEW_LINK_SOURCE.automatic | typeof RICH_PREVIEW_LINK_SOURCE.explicit;
+    start: number;
+    text: string;
+    url: string;
+}): RichPreviewSegment;
+/** Splits a matched bare URL from any trailing sentence punctuation. */
+export declare function splitBareUrlMatch(matchedUrl: string): {
+    trailingText: string;
+    urlText: string;
+};
+/** Whether two `[start, end)` ranges overlap. */
+export declare function rangesOverlap(firstRange: {
+    end: number;
+    start: number;
+}, secondRange: {
+    end: number;
+    start: number;
+}): boolean;
+/** Whether a matched bare URL is actually part of an email address. */
+export declare function isBareUrlMatchInsideEmail(input: {
+    content: string;
+    matchedIndex: number;
+    matchedUrl: string;
+}): boolean;
+/** Parses plain text into rendered segments, auto-linking bare URLs. */
+export declare function parseBareUrlSegments(content: string): RichTextSegment[];
+/** Parses plain text into editor preview segments, auto-linking bare URLs. */
+export declare function parseBareUrlPreviewSegments(content: string, offset: number, suppressedLinks: RichLink[]): RichPreviewSegment[];
+/**
+ * Parses the editor's plain-text content plus its tracked links into preview
+ * segments, layering explicit links over auto-detected bare URLs.
+ */
+export declare function parsePreviewSegments(content: string, links: RichLink[]): RichPreviewSegment[];
+/**
+ * Whether a markdown link whose URL is not a safe web link is a genuine
+ * suppressed autolink (`[some-url.com](#)`) produced by the editor, rather than
+ * literal text that merely looks like a markdown link (`[PDF](pendiente)`).
+ *
+ * Suppression only applies when the label itself is a normalizable URL, which
+ * mirrors `serializeEditorContent`. Any other `[text](url)` whose URL cannot be
+ * normalized is treated as authored plain text and preserved verbatim.
+ */
+export declare function isSuppressedAutolinkMarkdown(linkText: string, linkUrl: string): boolean;
+/**
+ * Parses persisted content (markdown links plus bare URLs) into rendered
+ * segments for read-only display.
+ */
+export declare function parseRichTextSegments(content: string): RichTextSegment[];
+/**
+ * Converts persisted markdown into the editor's plain-text content plus the
+ * tracked links (explicit and suppressed) needed to re-render it for editing.
+ */
+export declare function deserializeMarkdownForEditor(content: string): {
+    content: string;
+    links: RichLink[];
+};
+/**
+ * Serializes the editor's plain-text content plus tracked links back into
+ * persisted markdown, emitting `[text](url)` for explicit links and
+ * `[text](#)` for suppressed auto-detected URLs.
+ */
+export declare function serializeEditorContent(content: string, links: RichLink[]): string;
+/**
+ * Computes the minimal changed range between two strings: the common prefix
+ * end (`start`), the changed-region ends in each string, and the length delta.
+ */
+export declare function getTextDiff(input: {
+    nextText: string;
+    previousText: string;
+}): {
+    delta: number;
+    endInNextText: number;
+    endInPreviousText: number;
+    start: number;
+};
+/**
+ * Adjusts tracked link ranges after the editor's plain text changed, shifting,
+ * shrinking, or dropping links and keeping synchronized links in step with
+ * their visible text.
+ *
+ * A suppressed autolink is dropped once its visible text is no longer a
+ * normalizable URL, mirroring `isSuppressedAutolinkMarkdown`: with nothing left
+ * to suppress, the edited text serializes as plain text instead of `[text](#)`,
+ * which would otherwise be rendered back as literal markdown.
+ */
+export declare function getLinksAfterTextChange(input: {
+    links: RichLink[];
+    nextText: string;
+    previousText: string;
+}): RichLink[];