@hagicode/hagilight-core 0.8.1-dev.87.1.57ea49d → 0.8.1-dev.91.1.ab66a07

package/README.md

@@ -35,6 +35,36 @@ import { resolveSiteLinks } from '@hagicode/hagilight-core/links';
 const links = resolveSiteLinks('en-US');
 ```
 
+## Content images
+
+`@hagicode/hagilight-core/content-images` normalizes the `<img>` elements in Markdown and MDX body content at build time. A body image gets the marker class `hagilight-content-image`, `loading="lazy"`, and `decoding="async"`. Values the author already set are kept, existing classes are kept, and the marker is added once.
+
+| Option | Default | Accepted values |
+| --- | --- | --- |
+| `loading` | `lazy` | `lazy` or `eager`, applied only when the image has no `loading` |
+| `decoding` | `async` | `async`, `sync`, or `auto`, applied only when the image has no `decoding` |
+| `className` | `hagilight-content-image` | A class name without whitespace |
+
+Images inside a `<picture>` element are skipped. An MDX `class={expression}` gets no marker because its value is not known at build time. Raw HTML `<img>` tags inside a `.md` file are not normalized; use Markdown image syntax or MDX for body images.
+
+`hagilight()` from `@hagicode/hagilight-starlight` and `hagilight()` from `@hagicode/hagilight/integration` register the plugin automatically, for the whole site and regardless of integration order. Each one opts out through its `contentImages` option; see those packages' READMEs.
+
+To use the plugin without a feature package, add it to the Markdown processor. With the default Sätteri processor:
+
+```js
+import { defineConfig } from 'astro/config';
+import { satteri } from '@astrojs/markdown-satteri';
+import { satteriContentImages } from '@hagicode/hagilight-core/content-images';
+
+export default defineConfig({
+  markdown: {
+    processor: satteri({ hastPlugins: [satteriContentImages()] }),
+  },
+});
+```
+
+With the unified processor, pass `rehypeContentImages()` in `rehypePlugins` instead, from `@astrojs/markdown-remark`'s `unified()`. Integrations that wrap Astro can call `registerContentImages({ config, logger, enabled })` in `astro:config:setup` and `checkContentImageRegistration({ config, logger, enabled })` in `astro:config:done`, both exported from the same entry point.
+
 ## Promotion platforms
 
 The shared banner (`PromotoBanner`, `loadActivePromotions`) displays only promotions whose `platforms` array in Index's `/promote.json` includes `web`, in addition to being enabled, inside their activation window, and matched with `/promote_content.json`. This follows the `platforms` flag documented in the Index README. An entry whose `platforms` is missing, empty, or not an array of strings is not displayed, other values such as `hagicode` are ignored, and matching is exact (`Web` does not match). When no promotion remains, the banner shows its site fallback or stays hidden, as before.

package/dist/content-images.d.ts

@@ -0,0 +1,86 @@
+export declare const CONTENT_IMAGE_CLASS = "hagilight-content-image";
+export type ContentImageLoading = 'lazy' | 'eager';
+export type ContentImageDecoding = 'async' | 'sync' | 'auto';
+export interface ContentImageOptions {
+    /** Loading value for body images whose author set none. Defaults to `lazy`. */
+    loading?: ContentImageLoading;
+    /** Decoding value for body images whose author set none. Defaults to `async`. */
+    decoding?: ContentImageDecoding;
+    /** Marker class added once to every body image. Defaults to `hagilight-content-image`. */
+    className?: string;
+}
+export interface ResolvedContentImageOptions {
+    loading: ContentImageLoading;
+    decoding: ContentImageDecoding;
+    className: string;
+}
+export interface ContentImageAuthorValues {
+    hasLoading: boolean;
+    hasDecoding: boolean;
+    classNames: readonly string[];
+}
+export interface ContentImagePatch {
+    loading?: ContentImageLoading;
+    decoding?: ContentImageDecoding;
+    classNames?: string[];
+}
+export interface MdxAttributeLike {
+    type?: string;
+    name?: string;
+    value?: unknown;
+}
+export interface ContentImageNode {
+    type: string;
+    tagName?: string;
+    name?: string | null;
+    properties?: Record<string, unknown>;
+    attributes?: MdxAttributeLike[];
+    children?: ContentImageNode[];
+}
+export interface SatteriContentImageContext {
+    parent(node: unknown): unknown;
+    setProperty(node: unknown, key: string, value: unknown): void;
+}
+export interface SatteriContentImageVisitor {
+    filter: string[];
+    visit(node: ContentImageNode, ctx: SatteriContentImageContext): void;
+}
+export interface SatteriContentImagePlugin {
+    name: string;
+    element: SatteriContentImageVisitor;
+    mdxJsxFlowElement: SatteriContentImageVisitor;
+    mdxJsxTextElement: SatteriContentImageVisitor;
+}
+export interface ContentImageRegistrationInput {
+    config: {
+        markdown?: {
+            processor?: unknown;
+        };
+    };
+    logger: {
+        warn(message: string): void;
+    };
+    enabled: boolean;
+}
+export declare function resolveContentImageOptions(options?: ContentImageOptions): ResolvedContentImageOptions;
+export declare function contentImagePatch(author: ContentImageAuthorValues, options: ResolvedContentImageOptions): ContentImagePatch;
+export declare function hastImagePatch(properties: Record<string, unknown>, options: ResolvedContentImageOptions): ContentImagePatch;
+export interface MdxImagePatch {
+    loading?: ContentImageLoading;
+    decoding?: ContentImageDecoding;
+    className?: string;
+}
+/** A class written as an expression cannot be merged statically, so its marker is left out. */
+export declare function mdxImagePatch(attributes: readonly MdxAttributeLike[], options: ResolvedContentImageOptions): MdxImagePatch;
+/** Unified rehype plugin: `unified` processors and Astro 6 `markdown.rehypePlugins`. */
+export declare function rehypeContentImages(options?: ContentImageOptions): (tree: ContentImageNode) => void;
+/** Sätteri hast plugin: Astro's default Markdown processor, through `hastPlugins`. */
+export declare function satteriContentImages(options?: ContentImageOptions): SatteriContentImagePlugin;
+/**
+ * Register the content-image plugin on the active Markdown processor. The first enabled
+ * call appends one adapter; an `enabled: false` call opts the whole site out and removes
+ * only the adapter it did not append, so the result does not depend on hook order.
+ */
+export declare function registerContentImages({ config, logger, enabled }: ContentImageRegistrationInput): void;
+/** `astro:config:done` re-check: warns once if an enabled site's adapter is missing from the final processor. */
+export declare function checkContentImageRegistration({ config, logger, enabled }: ContentImageRegistrationInput): void;

package/dist/content-images.js

@@ -0,0 +1,234 @@
+export const CONTENT_IMAGE_CLASS = 'hagilight-content-image';
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function resolveContentImageOptions(options = {}) {
+    if (!isRecord(options))
+        throw new TypeError('Hagilight content image options must be an object.');
+    const { loading = 'lazy', decoding = 'async', className = CONTENT_IMAGE_CLASS } = options;
+    if (loading !== 'lazy' && loading !== 'eager') {
+        throw new TypeError('Hagilight content image loading option must be "lazy" or "eager".');
+    }
+    if (decoding !== 'async' && decoding !== 'sync' && decoding !== 'auto') {
+        throw new TypeError('Hagilight content image decoding option must be "async", "sync", or "auto".');
+    }
+    if (typeof className !== 'string' || className === '' || /\s/u.test(className)) {
+        throw new TypeError('Hagilight content image className option must be a non-empty class name without whitespace.');
+    }
+    return { loading, decoding, className };
+}
+export function contentImagePatch(author, options) {
+    const patch = {};
+    if (!author.hasLoading)
+        patch.loading = options.loading;
+    if (!author.hasDecoding)
+        patch.decoding = options.decoding;
+    if (!author.classNames.includes(options.className)) {
+        patch.classNames = [...author.classNames, options.className];
+    }
+    return patch;
+}
+function splitClassNames(value) {
+    return value.split(/\s+/u).filter(Boolean);
+}
+function classNamesOf(value) {
+    if (typeof value === 'string')
+        return splitClassNames(value);
+    if (Array.isArray(value)) {
+        return value.filter((item) => typeof item === 'string').flatMap(splitClassNames);
+    }
+    return [];
+}
+function mdxClassNames(attribute) {
+    if (attribute === undefined || attribute.value === undefined || attribute.value === null)
+        return [];
+    return typeof attribute.value === 'string' ? splitClassNames(attribute.value) : undefined;
+}
+export function hastImagePatch(properties, options) {
+    return contentImagePatch({
+        hasLoading: properties.loading !== undefined,
+        hasDecoding: properties.decoding !== undefined,
+        classNames: classNamesOf(properties.className),
+    }, options);
+}
+/** A class written as an expression cannot be merged statically, so its marker is left out. */
+export function mdxImagePatch(attributes, options) {
+    const classNames = mdxClassNames(attributes.find((attribute) => attribute.name === 'class'));
+    const patch = contentImagePatch({
+        hasLoading: attributes.some((attribute) => attribute.name === 'loading'),
+        hasDecoding: attributes.some((attribute) => attribute.name === 'decoding'),
+        classNames: classNames ?? [options.className],
+    }, options);
+    return {
+        loading: patch.loading,
+        decoding: patch.decoding,
+        className: patch.classNames?.join(' '),
+    };
+}
+function isMdxJsx(node) {
+    return node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement';
+}
+function isPicture(node) {
+    return (node.type === 'element' && node.tagName === 'picture')
+        || (isMdxJsx(node) && node.name === 'picture');
+}
+function upsertMdxAttribute(attributes, name, value) {
+    const existing = attributes.find((attribute) => attribute.name === name);
+    if (existing)
+        existing.value = value;
+    else
+        attributes.push({ type: 'mdxJsxAttribute', name, value });
+}
+function applyUnifiedNode(node, options) {
+    if (node.type === 'element' && node.tagName === 'img') {
+        const properties = (node.properties ??= {});
+        const patch = hastImagePatch(properties, options);
+        if (patch.loading !== undefined)
+            properties.loading = patch.loading;
+        if (patch.decoding !== undefined)
+            properties.decoding = patch.decoding;
+        if (patch.classNames !== undefined)
+            properties.className = patch.classNames;
+        return;
+    }
+    if (isMdxJsx(node) && node.name === 'img') {
+        const attributes = (node.attributes ??= []);
+        const patch = mdxImagePatch(attributes, options);
+        if (patch.loading !== undefined)
+            upsertMdxAttribute(attributes, 'loading', patch.loading);
+        if (patch.decoding !== undefined)
+            upsertMdxAttribute(attributes, 'decoding', patch.decoding);
+        if (patch.className !== undefined)
+            upsertMdxAttribute(attributes, 'class', patch.className);
+    }
+}
+function applyUnifiedTree(node, options, inPicture) {
+    if (!inPicture)
+        applyUnifiedNode(node, options);
+    const childrenInPicture = inPicture || isPicture(node);
+    for (const child of node.children ?? [])
+        applyUnifiedTree(child, options, childrenInPicture);
+}
+/** Unified rehype plugin: `unified` processors and Astro 6 `markdown.rehypePlugins`. */
+export function rehypeContentImages(options = {}) {
+    const resolved = resolveContentImageOptions(options);
+    return (tree) => {
+        applyUnifiedTree(tree, resolved, false);
+    };
+}
+function isInsidePicture(node, ctx) {
+    for (let parent = ctx.parent(node); parent; parent = ctx.parent(parent)) {
+        if (isPicture(parent))
+            return true;
+    }
+    return false;
+}
+/** Sätteri hast plugin: Astro's default Markdown processor, through `hastPlugins`. */
+export function satteriContentImages(options = {}) {
+    const resolved = resolveContentImageOptions(options);
+    const mdxVisitor = {
+        filter: ['img'],
+        visit(node, ctx) {
+            if (isInsidePicture(node, ctx))
+                return;
+            const patch = mdxImagePatch(node.attributes ?? [], resolved);
+            if (patch.loading !== undefined)
+                ctx.setProperty(node, 'loading', patch.loading);
+            if (patch.decoding !== undefined)
+                ctx.setProperty(node, 'decoding', patch.decoding);
+            if (patch.className !== undefined)
+                ctx.setProperty(node, 'class', patch.className);
+        },
+    };
+    return {
+        name: 'hagilight:content-images',
+        element: {
+            filter: ['img'],
+            visit(node, ctx) {
+                if (isInsidePicture(node, ctx))
+                    return;
+                const patch = hastImagePatch(node.properties ?? {}, resolved);
+                if (patch.loading !== undefined)
+                    ctx.setProperty(node, 'loading', patch.loading);
+                if (patch.decoding !== undefined)
+                    ctx.setProperty(node, 'decoding', patch.decoding);
+                if (patch.classNames !== undefined)
+                    ctx.setProperty(node, 'className', patch.classNames);
+            },
+        },
+        mdxJsxFlowElement: mdxVisitor,
+        mdxJsxTextElement: mdxVisitor,
+    };
+}
+const RECORD_KEY = Symbol.for('hagilight.content-images');
+function recordOf(processor) {
+    const holder = processor;
+    holder[RECORD_KEY] ??= { optedOut: false, warned: new Set() };
+    return holder[RECORD_KEY];
+}
+function pluginListOf(processor) {
+    const hastPlugins = processor.options?.hastPlugins;
+    const rehypePlugins = processor.options?.rehypePlugins;
+    if (processor.name === 'satteri' && Array.isArray(hastPlugins))
+        return hastPlugins;
+    if (processor.name === 'unified' && Array.isArray(rehypePlugins))
+        return rehypePlugins;
+    return undefined;
+}
+function warnOnce(record, key, logger, message) {
+    if (record.warned.has(key))
+        return;
+    record.warned.add(key);
+    logger.warn(message);
+}
+/**
+ * Register the content-image plugin on the active Markdown processor. The first enabled
+ * call appends one adapter; an `enabled: false` call opts the whole site out and removes
+ * only the adapter it did not append, so the result does not depend on hook order.
+ */
+export function registerContentImages({ config, logger, enabled }) {
+    const processor = config.markdown?.processor;
+    if (!processor) {
+        if (enabled) {
+            logger.warn('Hagilight content images need a Markdown processor, but the Astro config has none. Body images are left unchanged.');
+        }
+        return;
+    }
+    const record = recordOf(processor);
+    if (!enabled) {
+        record.optedOut = true;
+        if (record.list && record.entry !== undefined) {
+            const index = record.list.indexOf(record.entry);
+            if (index !== -1)
+                record.list.splice(index, 1);
+        }
+        record.entry = undefined;
+        record.list = undefined;
+        return;
+    }
+    if (record.optedOut || record.entry !== undefined)
+        return;
+    const list = pluginListOf(processor);
+    if (!list) {
+        warnOnce(record, 'unsupported', logger, `Hagilight content images cannot run on the "${String(processor.name)}" Markdown processor. Body images are left unchanged.`);
+        return;
+    }
+    const plugin = processor.name === 'satteri' ? satteriContentImages() : rehypeContentImages;
+    list.push(plugin);
+    record.entry = plugin;
+    record.list = list;
+}
+/** `astro:config:done` re-check: warns once if an enabled site's adapter is missing from the final processor. */
+export function checkContentImageRegistration({ config, logger, enabled }) {
+    if (!enabled)
+        return;
+    const processor = config.markdown?.processor;
+    if (!processor)
+        return;
+    const record = recordOf(processor);
+    if (record.optedOut || record.warned.has('unsupported'))
+        return;
+    if (record.entry !== undefined && pluginListOf(processor)?.includes(record.entry))
+        return;
+    warnOnce(record, 'lost', logger, `Hagilight content images were not found in the final "${String(processor.name)}" Markdown processor. Body images are left unchanged.`);
+}

package/dist/promotions.js

@@ -148,7 +148,7 @@ function localeCandidates(locale) {
         candidates.push('zh-cn', 'zh-hant', 'zh');
     }
     candidates.push('en-us', 'en');
-    return [...new Set(candidates)];
+    return Array.from(new Set(candidates));
 }
 function localized(value, locale) {
     const values = new Map(Object.entries(value).map(([key, text]) => [key.toLowerCase(), text]));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagilight-core",
-  "version": "0.8.1-dev.87.1.57ea49d",
+  "version": "0.8.1-dev.91.1.ab66a07",
   "type": "module",
   "description": "Shared TypeScript utilities, components, and assets for HagiCode Astro and Starlight sites",
   "repository": {
@@ -46,10 +46,18 @@
       "types": "./dist/promotions.d.ts",
       "default": "./dist/promotions.js"
     },
+    "./promoto-banner": {
+      "types": "./dist/promoto-banner.d.ts",
+      "default": "./dist/promoto-banner.js"
+    },
     "./analytics-events": {
       "types": "./dist/analytics-events.d.ts",
       "default": "./dist/analytics-events.js"
     },
+    "./content-images": {
+      "types": "./dist/content-images.d.ts",
+      "default": "./dist/content-images.js"
+    },
     "./Copyright": "./Copyright.astro",
     "./PromotoBanner": "./PromotoBanner.astro",
     "./GoogleAnalytics": "./GoogleAnalytics.astro",
@@ -69,6 +77,11 @@
   "peerDependencies": {
     "astro": "^6.0.7 || ^7.3.5"
   },
+  "peerDependenciesMeta": {
+    "astro": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "astro": "^7.3.5"
   },