@astra-kit/ui 0.0.0-stage → 0.0.0

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[];