vitepress-linkcard 1.3.0 → 2.0.0

package/dist/assemble/metadata.js

@@ -1,9 +1,37 @@
 import { parserMetadata, xhr } from '.';
 import LocalFileCache from './local-file-cache';
+/**
+ * Local file cache instance for storing fetched URL metadata.
+ * This cache persists metadata to disk to avoid repeated network requests.
+ * @internal
+ */
 const cache = new LocalFileCache();
 /**
- * @param url
- * @returns
+ * Retrieves metadata for a given URL, using cache when available.
+ *
+ * This function first checks if the metadata is already cached. If not, it fetches
+ * the HTML content from the URL, parses the metadata, and caches the result for
+ * future use.
+ *
+ * The metadata includes:
+ * - Title (from `<title>` or OGP tags)
+ * - Description (from meta description or OGP tags)
+ * - Logo/icon (from OGP image or favicon)
+ *
+ * @param url - The URL to fetch metadata from
+ * @returns The parsed URL metadata, or null if the URL cannot be fetched or parsed
+ *
+ * @example
+ * ```typescript
+ * const metadata = getUrlMetadata('https://example.com')
+ * if (metadata) {
+ *   console.log(metadata.title) // "Example Domain"
+ *   console.log(metadata.description) // "Example website description"
+ * }
+ * ```
+ *
+ * @see {@link parserMetadata} for details on metadata extraction
+ * @see {@link LocalFileCache} for caching implementation
  */
 export function getUrlMetadata(url) {
     if (cache.has(url))

package/dist/assemble/parser.js

@@ -1,22 +1,75 @@
 /**
- * TODO: Refactor
+ * HTML parser module for extracting metadata from web pages.
+ *
+ * This module provides functions to parse HTML strings and extract metadata such as
+ * title, description, and logo/icon URLs. It supports both standard HTML meta tags
+ * and Open Graph Protocol (OGP) tags.
+ *
+ * @module parser
+ * @todo Refactor to improve maintainability and add support for more meta tag formats
  */
 import { isString } from '@luckrya/utility';
 import { cleanPath, extractUrl } from './url';
+/**
+ * Default logo URL used when no logo can be extracted from the page.
+ */
 const DEFAULT_LOGO = 'https://resources.whatwg.org/logo-url.svg';
+/**
+ * Regular expression to match HTML tag content between opening and closing tags.
+ * @example Matches: `<title>Page Title</title>` → captures "Page Title"
+ */
 const HtmlTagContentReg = /(<[A-Za-z]+\s*[^>]*>(.*)<\/[A-Za-z]+>)/;
+/**
+ * Regular expression to extract the `content` attribute value from HTML meta tags.
+ * @example Matches: `content="value"` or `content='value'`
+ */
 const ContentAttrValueHtmlMetaTagReg = /content=["|']([^>]*)["|']/;
+/**
+ * Regular expression to extract the `href` attribute value from HTML link tags.
+ * @example Matches: `href="value"` or `href='value'`
+ */
 const HrefAttrValueHtmlLinkTagReg = /href=["|']([^>]*)["|']/;
+/**
+ * Regular expression to match HTML title tags.
+ * @example Matches: `<title>Page Title</title>`
+ */
 const HtmlTitleTagReg = /(<title\s*[^>]*>(.*)<\/title>)/g;
-// const HtmlMetaTagReg = /<meta\s[^>]*\/?>/g;
-// const HtmlLinkTagReg = /<link\s[^>]*\/?>/g;
+/**
+ * Creates a regular expression to match self-closing or non-closing HTML tags with a specific attribute.
+ *
+ * This function generates patterns to find meta or link tags that contain a specific attribute,
+ * which is useful for finding OGP tags like `og:title`, `og:description`, etc.
+ *
+ * @param attr - The attribute to search for (e.g., 'title', 'description', 'image')
+ * @param tag - The HTML tag name to match (default: 'meta')
+ * @returns A RegExp that matches tags containing the specified attribute
+ *
+ * @example
+ * ```typescript
+ * const reg = containArrSelfLosingHtmlTagReg('og:title')
+ * // Matches: <meta property="og:title" content="...">
+ * ```
+ *
+ * @internal
+ */
 const containArrSelfLosingHtmlTagReg = (attr, tag = 'meta') => new RegExp(`<${tag}\\s[^>]*\\w+=['|"]([a-zA-Z]|:|\\s)*${attr}['|"][^>]*\\/?>`);
 /**
- * @param htmlString
- * @returns
- *   <title>$value</title>
- *   <meta property="og:title" content="$value" />
- *   <link data-react-helmet="true" href="https://s.xml" rel="search" title="$value" type="applon+xml">
+ * Extracts the page title from HTML string.
+ *
+ * Attempts to find the title in the following order:
+ * 1. Meta tags with 'title' attribute (e.g., `<meta property="og:title" content="...">`)
+ * 2. Standard HTML `<title>` tag
+ *
+ * @param htmlString - The HTML content to parse
+ * @returns The extracted title, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const title = matchTitleByMetaTag('<title>Example Page</title>')
+ * // Returns: "Example Page"
+ * ```
+ *
+ * @internal
  */
 function matchTitleByMetaTag(htmlString) {
     let title;
@@ -37,9 +90,22 @@ function matchTitleByMetaTag(htmlString) {
     return title;
 }
 /**
- * @returns
- *   <meta name="description" content="$value" />
- *   <meta property="og:description" content="$value" />
+ * Extracts the page description from HTML string.
+ *
+ * Searches for description in meta tags, supporting both standard and OGP formats:
+ * - `<meta name="description" content="...">`
+ * - `<meta property="og:description" content="...">`
+ *
+ * @param htmlString - The HTML content to parse
+ * @returns The extracted description, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const desc = matchDescriptionByMetaTag('<meta name="description" content="A great site">')
+ * // Returns: "A great site"
+ * ```
+ *
+ * @internal
  */
 function matchDescriptionByMetaTag(htmlString) {
     let description;
@@ -52,9 +118,22 @@ function matchDescriptionByMetaTag(htmlString) {
     return description;
 }
 /**
- * @returns
- *   <meta property="og:image" content="$value" />
- *   <link rel="icon" href="$value">
+ * Extracts the page logo/icon URL from HTML string.
+ *
+ * Attempts to find the logo in the following order:
+ * 1. OGP image tag: `<meta property="og:image" content="...">`
+ * 2. Icon link tag: `<link rel="icon" href="...">`
+ *
+ * @param htmlString - The HTML content to parse
+ * @returns The extracted logo URL (may be relative), or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const logo = matchLogoByLinkOrMetaTag('<link rel="icon" href="/favicon.ico">')
+ * // Returns: "/favicon.ico"
+ * ```
+ *
+ * @internal
  */
 function matchLogoByLinkOrMetaTag(htmlString) {
     let logo;
@@ -76,11 +155,39 @@ function matchLogoByLinkOrMetaTag(htmlString) {
     return logo;
 }
 /**
- * @param htmlString
- * @param url
- * @returns
+ * Parses HTML string to extract structured metadata for link card generation.
+ *
+ * This is the main parsing function that extracts title, description, and logo
+ * from an HTML page. It handles both absolute and relative URLs, converting
+ * relative logo paths to absolute URLs when necessary.
+ *
+ * @param htmlString - The HTML content to parse
+ * @param url - The URL of the page (used to resolve relative logo URLs)
+ * @returns Parsed metadata object, or null if no valid metadata could be extracted
+ *
+ * @example
+ * ```typescript
+ * const html = '<title>Example</title><meta name="description" content="Test">'
+ * const metadata = parserMetadata(html, 'https://example.com')
+ * // Returns: { title: 'Example', description: 'Test', logo: '...' }
+ * ```
+ *
+ * @remarks
+ * - Returns null if all metadata fields (title, description, logo) are empty
+ * - Relative logo URLs are converted to absolute URLs using the page's origin
+ * - Falls back to a default logo if no logo can be found
+ *
+ * @todo Handle protocol-relative URLs like `//img.example.com/logo.png`
  */
 export function parserMetadata(htmlString, url) {
+    /**
+     * Converts a potentially relative logo URL to an absolute URL.
+     *
+     * @param logo - The logo URL (may be relative or absolute)
+     * @returns Absolute URL for the logo, or default logo if input is invalid
+     *
+     * @internal
+     */
     function absolute(logo) {
         if (!logo)
             return DEFAULT_LOGO;
@@ -99,8 +206,15 @@ export function parserMetadata(htmlString, url) {
         return metadata;
 }
 /**
- * @param obj
- * @returns
+ * Checks if an object contains only undefined or empty string values.
+ *
+ * This utility function is used to determine if any valid metadata was extracted
+ * from a page. If all fields are empty, the metadata is considered invalid.
+ *
+ * @param obj - Object to check (typically a metadata object)
+ * @returns true if the object has no non-empty string values, false otherwise
+ *
+ * @internal
  */
 function isEmptyStringObject(obj) {
     return !Object.values(obj).filter((v) => isString(v)).length;

package/dist/assemble/style.js

@@ -1,13 +1,48 @@
 /**
- * @param str
- * @returns
+ * Style generation utilities for link card rendering.
+ *
+ * This module provides functions to generate inline CSS styles and class names
+ * for the link card components. The styles support customizable colors and
+ * responsive design with text ellipsis for long content.
+ *
+ * @module style
+ */
+/**
+ * Converts a camelCase string to hyphenated kebab-case.
+ *
+ * This is used to convert JavaScript style property names (e.g., `backgroundColor`)
+ * to CSS property names (e.g., `background-color`).
+ *
+ * @param str - The camelCase string to convert
+ * @returns The hyphenated kebab-case string
+ *
+ * @example
+ * ```typescript
+ * hyphenate('backgroundColor') // Returns: 'background-color'
+ * hyphenate('fontSize')        // Returns: 'font-size'
+ * ```
+ *
+ * @internal
  */
 function hyphenate(str) {
     return str.replace(/\B([A-Z])/g, '-$1').toLowerCase();
 }
 /**
- * @param style
- * @returns
+ * Joins style properties into a CSS string.
+ *
+ * Converts a JavaScript object of style properties into a semicolon-separated
+ * CSS string suitable for inline styles.
+ *
+ * @param style - Object containing CSS properties and values
+ * @returns A string of CSS declarations
+ *
+ * @example
+ * ```typescript
+ * join({ fontSize: '16px', color: 'red' })
+ * // Returns: 'font-size: 16px; color: red;'
+ * ```
+ *
+ * @internal
  */
 function join(style) {
     return Object.entries(style)
@@ -19,15 +54,38 @@ function join(style) {
         .join(' ');
 }
 /**
- * @param style
- * @returns
+ * Wraps CSS declarations in an inline style attribute.
+ *
+ * @param style - Object containing CSS properties and values
+ * @returns A complete HTML style attribute string
+ *
+ * @example
+ * ```typescript
+ * inlineStyle({ color: 'red', fontSize: '16px' })
+ * // Returns: 'style="color: red; font-size: 16px;"'
+ * ```
+ *
+ * @internal
  */
 function inlineStyle(style) {
     return `style="${join(style)}"`;
 }
 /**
- * @param line
- * @returns
+ * Generates CSS properties for text ellipsis with line clamping.
+ *
+ * Creates styles that truncate text after a specified number of lines with
+ * an ellipsis. Uses both WebKit-specific properties and standard line-clamp.
+ *
+ * @param line - Maximum number of lines to display before truncation
+ * @returns CSS properties object for ellipsis effect
+ *
+ * @example
+ * ```typescript
+ * ellipsisStyle(2)
+ * // Returns styles that truncate text after 2 lines with "..."
+ * ```
+ *
+ * @internal
  */
 const ellipsisStyle = (line) => ({
     '-webkit-box-orient': 'vertical',
@@ -41,12 +99,33 @@ const ellipsisStyle = (line) => ({
     wordBreak: 'break-word'
 });
 /**
- See: * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/components/VPFeature.vue
- * @param borderColor
- * @param bgColor
- * @returns
+ * Generates complete inline styles for all link card components.
+ *
+ * Creates a set of inline style strings for each part of the link card:
+ * - Container: main card box with border and background
+ * - Image: logo/icon display
+ * - Texts: wrapper for text content
+ * - Title: card title (2-line ellipsis)
+ * - Domain: domain name with underline
+ * - Description: description text (2-line ellipsis)
+ *
+ * The styles are inspired by VitePress's VPFeature component design.
+ *
+ * The container uses CSS custom properties for theming:
+ * - `--vitepress-linkcard-border-color`: Border color (default: #7d7d7dff)
+ * - `--vitepress-linkcard-bg-color`: Background color (default: transparent)
+ *
+ * @returns Object containing style attribute strings for each card component
+ *
+ * @example
+ * ```typescript
+ * const styles = STYLE()
+ * // Use in HTML: <div ${styles.container}>...</div>
+ * ```
+ *
+ * @see {@link https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/components/VPFeature.vue | VPFeature component}
  */
-export const STYLE = (borderColor, bgColor) => ({
+export const STYLE = () => ({
     a: inlineStyle({
         color: 'unset !important',
         display: 'block',
@@ -59,11 +138,12 @@ export const STYLE = (borderColor, bgColor) => ({
         flexWrap: 'wrap',
         gap: '10px',
         borderRadius: '12px',
-        border: `1px solid ${borderColor}`,
-        backgroundColor: bgColor,
+        border: `1px solid var(--vp-c-bg-soft)`,
+        backgroundColor: `var(--vp-c-bg-soft)`,
         boxSizing: 'border-box',
         width: '100%',
-        height: '130px'
+        height: '130px',
+        transition: 'border-color 0.25s, background-color 0.25s'
     }),
     img: inlineStyle({
         borderRadius: '0px 12px 12px 0px',
@@ -102,8 +182,27 @@ export const STYLE = (borderColor, bgColor) => ({
     })
 });
 /**
- * @param prefix
- * @returns
+ * Generates CSS class names with a custom prefix.
+ *
+ * When using the `classPrefix` option, this function creates consistent
+ * class names for all card components following a BEM-like naming convention.
+ *
+ * @param prefix - The prefix to prepend to all class names
+ * @returns Object mapping component names to their class names
+ *
+ * @example
+ * ```typescript
+ * const classes = classNames('my-card')
+ * // Returns: {
+ * //   container: 'my-card__container',
+ * //   title: 'my-card__texts--title',
+ * //   ...
+ * // }
+ * ```
+ *
+ * @remarks
+ * When class names are used instead of inline styles, you must provide
+ * your own CSS definitions for these classes.
  */
 export const classNames = (prefix) => ({
     container: `${prefix}__container`,

package/dist/assemble/url.js

@@ -1,13 +1,44 @@
 /**
- * @param url
- * @returns
+ * URL utility functions for parsing and manipulating URLs.
+ *
+ * @module url
+ */
+/**
+ * Parses a URL string and returns a URL object.
+ *
+ * This is a wrapper around the native URL constructor that provides
+ * a consistent interface for URL parsing throughout the codebase.
+ *
+ * @param url - The URL string to parse
+ * @returns A URL object containing the parsed components
+ * @throws {TypeError} If the URL string is invalid
+ *
+ * @example
+ * ```typescript
+ * const urlObj = extractUrl('https://example.com/path')
+ * console.log(urlObj.origin) // "https://example.com"
+ * console.log(urlObj.pathname) // "/path"
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/URL | MDN - URL}
  */
 export function extractUrl(url) {
     return new URL(url);
 }
 /**
- * @param path
- * @returns
+ * Removes duplicate consecutive slashes from a path string.
+ *
+ * This function normalizes paths by replacing multiple consecutive slashes
+ * with a single slash. Useful for constructing clean URLs from path segments.
+ *
+ * @param path - The path string to clean
+ * @returns The cleaned path with no consecutive slashes
+ *
+ * @example
+ * ```typescript
+ * cleanPath('/path//to///file')  // Returns: '/path/to/file'
+ * cleanPath('//images//logo.png') // Returns: '/images/logo.png'
+ * ```
  */
 export function cleanPath(path) {
     return path.replace(/\/\//g, '/');

package/dist/assemble/xhr.js

@@ -1,13 +1,52 @@
+/**
+ * XHR module for fetching remote URL content.
+ *
+ * This module provides both synchronous and asynchronous HTTP GET request functionality
+ * with built-in caching. It works in both browser and Node.js environments by using
+ * the appropriate XMLHttpRequest implementation.
+ *
+ * @module xhr
+ * @todo Replace xmlhttprequest with a modern alternative (e.g., node-fetch or axios)
+ */
 // Refactor: xmlhttprequest will be replaced later
 // @ts-expect-error: xmlhttprequest has no types
 import xhrForNode from 'xmlhttprequest';
 import { inBrowser, isString } from '@luckrya/utility';
-// TODO: Local File Cache
+/**
+ * In-memory cache for storing fetched HTML content by URL.
+ * Prevents redundant network requests for the same URLs.
+ * @internal
+ */
 const cache = new Map();
+/**
+ * XMLHttpRequest implementation that works in both browser and Node.js.
+ * @internal
+ */
 const XHR = inBrowser ? window.XMLHttpRequest : xhrForNode.XMLHttpRequest;
 /**
- * @param url
- * @returns
+ * Performs a synchronous HTTP GET request to fetch HTML content from a URL.
+ *
+ * This function fetches the content synchronously, which means it blocks execution
+ * until the request completes. The response is cached to avoid redundant requests.
+ *
+ * @param url - The URL to fetch content from
+ * @returns The HTML content as a string, or undefined if the request fails
+ *
+ * @example
+ * ```typescript
+ * const html = sync('https://example.com')
+ * if (html) {
+ *   console.log('Fetched HTML content')
+ * }
+ * ```
+ *
+ * @remarks
+ * - Returns cached content if available
+ * - Only returns content if HTTP status is 200
+ * - Errors are logged to console but not thrown
+ * - Synchronous requests block the event loop - use with caution
+ *
+ * @see {@link async} for an asynchronous alternative
  */
 export function sync(url) {
     if (cache.has(url))
@@ -29,8 +68,35 @@ export function sync(url) {
     return result;
 }
 /**
- * @param url
- * @returns
+ * Performs an asynchronous HTTP GET request to fetch HTML content from a URL.
+ *
+ * This function fetches content asynchronously using Promises. The response is
+ * cached to avoid redundant requests.
+ *
+ * @param url - The URL to fetch content from
+ * @returns A Promise that resolves to the HTML content string, or undefined if the request fails
+ *
+ * @example
+ * ```typescript
+ * async function fetchPage() {
+ *   try {
+ *     const html = await async('https://example.com')
+ *     if (html) {
+ *       console.log('Fetched HTML content')
+ *     }
+ *   } catch (error) {
+ *     console.error('Failed to fetch:', error)
+ *   }
+ * }
+ * ```
+ *
+ * @remarks
+ * - Returns cached content if available
+ * - Only resolves with content if HTTP status is 200 and readyState is 4
+ * - Promise is rejected if the request throws an error
+ * - Preferred over `sync()` for non-blocking operations
+ *
+ * @see {@link sync} for a synchronous alternative
  */
 export function async(url) {
     return new Promise((resolve, reject) => {