@master/css-server 2.0.0-rc.69 → 2.0.0-rc.70

package/README.md

@@ -41,16 +41,58 @@
             <img alt="Follow @mastercorg" src="https://img.shields.io/static/v1?label=%20&message=twitter&color=f6f7f8&logo=twitter&style=for-the-badge">
         </picture>
     </a>
-    <a aria-label="Github Actions" href="https://github.com/master-co/css/actions/workflows/release.yml">
+    <a aria-label="Github Actions" href="https://github.com/master-co/css/actions/workflows/ci-release.yml">
         <picture>
-            <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/github/actions/workflow/status/master-co/css/release.yml?branch=rc&label=%20&message=twitter&color=212022&logo=githubactions&style=for-the-badge">
-            <source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/github/actions/workflow/status/master-co/css/release.yml?branch=rc&label=%20&message=twitter&color=f6f7f8&logo=githubactions&style=for-the-badge&logoColor=%23000">
-            <img alt="Github release actions" src="https://img.shields.io/github/actions/workflow/status/master-co/css/release.yml?branch=rc&label=%20&message=twitter&color=f6f7f8&logo=githubactions&style=for-the-badge&logoColor=%23000">
+            <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/github/actions/workflow/status/master-co/css/ci-release.yml?branch=rc&label=%20&message=twitter&color=212022&logo=githubactions&style=for-the-badge">
+            <source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/github/actions/workflow/status/master-co/css/ci-release.yml?branch=rc&label=%20&message=twitter&color=f6f7f8&logo=githubactions&style=for-the-badge&logoColor=%23000">
+            <img alt="Github release actions" src="https://img.shields.io/github/actions/workflow/status/master-co/css/ci-release.yml?branch=rc&label=%20&message=twitter&color=f6f7f8&logo=githubactions&style=for-the-badge&logoColor=%23000">
         </picture>
     </a>
 </p>
 
 </div>
 
-## Documentation
-Check out the official [documentation](https://rc.css.master.co/reference/server).
+## Installation
+
+```bash
+npm install @master/css-server
+```
+
+`@master/css-server` renders required Master CSS from HTML. It parses HTML, extracts class names, creates a `MasterCSS` instance, and injects or updates `<style id="master-css">`.
+
+## API
+
+### `render()`
+
+Render HTML and inject generated CSS.
+
+```ts
+import { render } from '@master/css-server'
+
+const result = render('<div class="text:center"></div>', manifest)
+
+console.log(result.html)
+console.log(result.css.text)
+```
+
+### `renderCSS()`
+
+Render only the CSS needed by an HTML string.
+
+```ts
+import { renderCSS } from '@master/css-server'
+
+const css = renderCSS('<div class="text:center"></div>', manifest)
+```
+
+### `parseHTML()`
+
+Parse HTML into the lightweight DOM representation used by the server renderer.
+
+```ts
+import { parseHTML } from '@master/css-server'
+
+const document = parseHTML('<html><head></head><body></body></html>')
+```
+
+Use official framework integrations when possible; they compose this package with manifest loading, source scanning, and runtime hydration.

package/dist/create-server-css.d.ts

@@ -0,0 +1,2 @@
+import { createCSSWithNativeDeclarations } from '@master/css-validator';
+export default createCSSWithNativeDeclarations;

package/dist/create-server-css.mjs

@@ -0,0 +1,2 @@
+import { createCSSWithNativeDeclarations } from '@master/css-validator';
+export { createCSSWithNativeDeclarations as default } from '@master/css-validator';

package/dist/default-manifest.d.ts

@@ -0,0 +1,2 @@
+import type { MasterCSSManifest } from '@master/css-schema/manifest';
+export default function getDefaultManifest(): MasterCSSManifest;

package/dist/default-manifest.mjs

@@ -0,0 +1,8 @@
+import defaultManifestJSON from '@master/css-preset/default-manifest.json' with { type: 'json' };
+
+const defaultManifest = defaultManifestJSON;
+function getDefaultManifest() {
+    return defaultManifest;
+}
+
+export { getDefaultManifest as default };

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export { default as render } from './render';
+export type { RenderOptions, RenderResult, RenderHydrationManifestOption } from './render';
 export { default as renderCSS } from './render-css';
 export { default as parseHTML } from './parse-html';
+export { default as createServerCSS } from './create-server-css';

package/dist/index.mjs

@@ -1,3 +1,4 @@
 export { default as render } from './render.mjs';
 export { default as renderCSS } from './render-css.mjs';
 export { default as parseHTML } from './parse-html.mjs';
+export { createCSSWithNativeDeclarations as createServerCSS } from '@master/css-validator';

package/dist/parse-html.mjs

@@ -1,4 +1,5 @@
 import { DomHandler, Parser } from 'htmlparser2';
+import { MASTER_CSS_RUNTIME_STYLE_ID } from '@master/css-schema/runtime-style';
 import decodeHTML from './decode-html.mjs';
 
 /**
@@ -20,10 +21,11 @@ import decodeHTML from './decode-html.mjs';
                     break;
             }
         } else if (element.type === 'style') {
-            if (element.attribs.id === 'master') styleElement = element;
+            if (element.attribs.id === MASTER_CSS_RUNTIME_STYLE_ID) styleElement = element;
         }
         if (element.attribs.class) {
-            element.attribs.class.split(' ').forEach((className)=>{
+            element.attribs.class.trim().split(/\s+/).forEach((className)=>{
+                if (!className) return;
                 className = decodeHTML(className);
                 if (!classes.includes(className)) classes.push(className);
             });

package/dist/render-css.d.ts

@@ -1,8 +1,9 @@
-import { MasterCSS, Config } from '@master/css';
+import { MasterCSS } from '@master/css';
+import type { MasterCSSManifest } from '@master/css-schema/manifest';
 /**
  * Renders the Master CSS string from HTML
  * @param html
- * @param config
+ * @param manifest
  * @returns MasterCSS
  */
-export default function renderCSS(html: string, config?: Config): MasterCSS | undefined;
+export default function renderCSS(html: string, manifest?: MasterCSSManifest): MasterCSS | undefined;

package/dist/render-css.mjs

@@ -1,16 +1,17 @@
 import parseHTML from './parse-html.mjs';
-import { createCSS } from '@master/css';
+import getDefaultManifest from './default-manifest.mjs';
+import { createCSSWithNativeDeclarations } from '@master/css-validator';
 
 /**
  * Renders the Master CSS string from HTML
  * @param html
- * @param config
+ * @param manifest
  * @returns MasterCSS
- */ function renderCSS(html, config) {
+ */ function renderCSS(html, manifest) {
     if (!html) return;
     const { classes } = parseHTML(html);
     if (!classes.length) return;
-    const css = createCSS(config);
+    const css = createCSSWithNativeDeclarations(manifest || getDefaultManifest());
     classes.forEach((eachClass)=>css.add(eachClass));
     return css;
 }

package/dist/render.d.ts

@@ -1,11 +1,17 @@
-import { MasterCSS, Config } from '@master/css';
+import { MasterCSS } from '@master/css';
+import type { MasterCSSManifest } from '@master/css-schema/manifest';
+import { type MasterCSSHydrationManifest } from '@master/css-schema/hydration-manifest';
 import { Element, ChildNode } from 'domhandler';
-/**
- * Renders the page-required and sorted CSS text from HTML and injected it back into HTML
- * @param html
- * @param config
- */
-export default function render(html: string, config?: Config): {
+export type RenderExternalHydrationManifestSource = string | ((json: string, hydrationManifest: MasterCSSHydrationManifest) => string);
+export interface RenderExternalHydrationManifestOption {
+    type: 'external';
+    src: RenderExternalHydrationManifestSource;
+}
+export type RenderHydrationManifestOption = 'return' | 'inject' | false | RenderExternalHydrationManifestOption;
+export interface RenderOptions {
+    hydrationManifest?: RenderHydrationManifestOption;
+}
+export interface RenderResult {
     html: string;
     css?: MasterCSS;
     classes: string[];
@@ -13,4 +19,11 @@ export default function render(html: string, config?: Config): {
     htmlElement: Element | null;
     headElement: Element | null;
     styleElement: Element | null;
-};
+    hydrationManifest?: MasterCSSHydrationManifest;
+}
+/**
+ * Renders the page-required and sorted CSS text from HTML and injected it back into HTML
+ * @param html
+ * @param manifest
+ */
+export default function render(html: string, manifest?: MasterCSSManifest, options?: RenderOptions): RenderResult;

package/dist/render.mjs

@@ -1,33 +1,170 @@
-import { createCSS } from '@master/css';
+import { createHydrationManifest } from '@master/css';
+import { MASTER_CSS_HYDRATION_MANIFEST_ATTR, serializeMasterCSSHydrationManifest, MASTER_CSS_HYDRATION_MANIFEST_SCRIPT_ID } from '@master/css-schema/hydration-manifest';
+import { MASTER_CSS_RUNTIME_STYLE_ID } from '@master/css-schema/runtime-style';
 import parseHTML from './parse-html.mjs';
+import getDefaultManifest from './default-manifest.mjs';
+import { createCSSWithNativeDeclarations } from '@master/css-validator';
 import { Text, Element } from 'domhandler';
 import serialize from 'dom-serializer';
 
+function createHydrationManifestScript(hydrationManifest) {
+    return new Element('script', {
+        type: 'application/json',
+        id: MASTER_CSS_HYDRATION_MANIFEST_SCRIPT_ID
+    }, [
+        new Text(serializeMasterCSSHydrationManifest(hydrationManifest))
+    ]);
+}
+function isHydrationManifestScript(node) {
+    return node.type === 'script' && node.name === 'script' && node.attribs.id === MASTER_CSS_HYDRATION_MANIFEST_SCRIPT_ID;
+}
+function setHydrationManifestScript(element, hydrationManifest) {
+    element.attribs.type = 'application/json';
+    element.attribs.id = MASTER_CSS_HYDRATION_MANIFEST_SCRIPT_ID;
+    element.childNodes = [
+        new Text(serializeMasterCSSHydrationManifest(hydrationManifest))
+    ];
+}
+function isExternalHydrationManifestOption(hydrationManifest) {
+    return typeof hydrationManifest === 'object' && hydrationManifest?.type === 'external';
+}
+function getExternalHydrationManifestSource(option, hydrationManifest) {
+    const json = serializeMasterCSSHydrationManifest(hydrationManifest);
+    return typeof option.src === 'function' ? option.src(json, hydrationManifest) : option.src;
+}
+function findHydrationManifestScripts(childNodes, matches = []) {
+    for(let index = 0; index < childNodes.length; index++){
+        const node = childNodes[index];
+        if (isHydrationManifestScript(node)) {
+            matches.push({
+                element: node,
+                childNodes,
+                index
+            });
+        }
+        if ('childNodes' in node) {
+            findHydrationManifestScripts(node.childNodes, matches);
+        }
+    }
+    return matches;
+}
+function removeNode(nodes, target) {
+    const index = nodes.indexOf(target);
+    if (index !== -1) {
+        nodes.splice(index, 1);
+        return true;
+    }
+    for (const node of nodes){
+        if ('childNodes' in node && removeNode(node.childNodes, target)) {
+            return true;
+        }
+    }
+    return false;
+}
+function removeHydrationManifestScripts(nodes) {
+    const existingScripts = findHydrationManifestScripts(nodes);
+    for(let index = existingScripts.length - 1; index >= 0; index--){
+        const script = existingScripts[index];
+        script.childNodes.splice(script.index, 1);
+    }
+    return existingScripts.length > 0;
+}
+function removeExternalHydrationManifest(styleElement) {
+    if (styleElement) {
+        delete styleElement.attribs[MASTER_CSS_HYDRATION_MANIFEST_ATTR];
+    }
+}
+function injectExternalHydrationManifest(nodes, styleElement, src) {
+    removeHydrationManifestScripts(nodes);
+    if (styleElement) {
+        styleElement.attribs[MASTER_CSS_HYDRATION_MANIFEST_ATTR] = src;
+    }
+}
+function injectHydrationManifest(nodes, htmlElement, headElement, styleElement, hydrationManifest) {
+    removeExternalHydrationManifest(styleElement);
+    const existingScripts = findHydrationManifestScripts(nodes);
+    if (existingScripts.length) {
+        const [firstScript, ...duplicateScripts] = existingScripts;
+        setHydrationManifestScript(firstScript.element, hydrationManifest);
+        for(let index = duplicateScripts.length - 1; index >= 0; index--){
+            const script = duplicateScripts[index];
+            script.childNodes.splice(script.index, 1);
+        }
+        return;
+    }
+    const scriptElement = createHydrationManifestScript(hydrationManifest);
+    if (headElement) {
+        headElement.childNodes.push(scriptElement);
+    } else if (htmlElement) {
+        headElement = new Element('head', {}, [
+            scriptElement
+        ]);
+        htmlElement.childNodes.unshift(headElement);
+    } else {
+        const styleElementIndex = styleElement ? nodes.indexOf(styleElement) : -1;
+        if (styleElementIndex === -1) {
+            nodes.unshift(scriptElement);
+        } else {
+            nodes.splice(styleElementIndex + 1, 0, scriptElement);
+        }
+    }
+}
 /**
  * Renders the page-required and sorted CSS text from HTML and injected it back into HTML
  * @param html
- * @param config
- */ function render(html, config) {
+ * @param manifest
+ */ function render(html, manifest, options = {}) {
     const context = parseHTML(html);
     const { classes, nodes, htmlElement } = context;
     let { headElement, styleElement } = context;
+    const externalHydrationManifestOption = isExternalHydrationManifestOption(options.hydrationManifest) ? options.hydrationManifest : undefined;
+    if (!classes.length && externalHydrationManifestOption) {
+        removeHydrationManifestScripts(nodes);
+        removeExternalHydrationManifest(styleElement);
+    }
     if (!classes.length) return {
-        html,
+        html: externalHydrationManifestOption ? serialize(nodes, {
+            decodeEntities: false,
+            encodeEntities: false
+        }) : html,
         classes,
         nodes,
         htmlElement,
         headElement,
         styleElement
     };
-    const css = createCSS(config);
+    const css = createCSSWithNativeDeclarations(manifest || getDefaultManifest());
     classes.forEach((eachClass)=>css.add(eachClass));
+    const hydrationManifest = options.hydrationManifest === false ? undefined : createHydrationManifest(css);
+    if (!css.text) {
+        if ((options.hydrationManifest === 'inject' || externalHydrationManifestOption) && styleElement) {
+            removeNode(nodes, styleElement);
+            styleElement = null;
+        }
+        if (externalHydrationManifestOption) {
+            removeHydrationManifestScripts(nodes);
+        }
+        return {
+            html: serialize(nodes, {
+                decodeEntities: false,
+                encodeEntities: false
+            }),
+            css,
+            classes,
+            hydrationManifest,
+            nodes,
+            htmlElement,
+            headElement,
+            styleElement
+        };
+    }
     if (styleElement) {
         styleElement.childNodes = [
             new Text(css.text)
         ];
     } else {
         styleElement = new Element('style', {
-            id: 'master'
+            id: MASTER_CSS_RUNTIME_STYLE_ID
         }, [
             new Text(css.text)
         ]);
@@ -44,6 +181,13 @@ import serialize from 'dom-serializer';
             }
         }
     }
+    if (options.hydrationManifest === 'inject' && hydrationManifest?.rules.length) {
+        injectHydrationManifest(nodes, htmlElement, headElement, styleElement, hydrationManifest);
+    } else if (externalHydrationManifestOption && hydrationManifest?.rules.length) {
+        injectExternalHydrationManifest(nodes, styleElement, getExternalHydrationManifestSource(externalHydrationManifestOption, hydrationManifest));
+    } else {
+        removeExternalHydrationManifest(styleElement);
+    }
     return {
         html: serialize(nodes, {
             decodeEntities: false,
@@ -51,6 +195,7 @@ import serialize from 'dom-serializer';
         }),
         css,
         classes,
+        hydrationManifest,
         nodes,
         htmlElement,
         headElement,

package/package.json

@@ -1 +1 @@
-{"name":"@master/css-server","type":"module","scripts":{"build":"techor build \"src/**/*.ts\"","dev":"pnpm build --watch","lint":"eslint","type-check":"tsc --noEmit","test":"vitest"},"license":"MIT","description":"Render Master CSS on the server side","author":"Aoyue Design LLC.","funding":"https://rc.css.master.co/sponsor","homepage":"https://css.master.co","bugs":{"url":"https://github.com/master-co/css/issues"},"repository":{"type":"git","url":"https://github.com/master-co/css.git","directory":"packages/server"},"keywords":["server","static","html","markup","dom","css","mastercss"],"sideEffects":false,"main":"./dist/index.cjs","module":"./dist/index.mjs","jsnext:main":"./dist/index.mjs","esnext":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.cjs"}},"files":["dist"],"publishConfig":{"access":"public","provenance":true},"dependencies":{"@master/css":"^2.0.0-rc.69","dom-serializer":"^2.0.0","domhandler":"^5.0.3","htmlparser2":"^10.0.0"},"devDependencies":{"shared":"^2.0.0-rc.69"},"version":"2.0.0-rc.69"}
+{"name":"@master/css-server","type":"module","scripts":{"build":"techor build \"src/**/*.ts\" --formats esm && node scripts/restore-json-import-attributes.mjs","dev":"pnpm build --watch","lint":"eslint","type-check":"tsc --noEmit","test":"vitest"},"license":"MIT","description":"Render Master CSS on the server side","author":"Aoyue Design LLC.","funding":"https://rc.css.master.co/sponsor","homepage":"https://css.master.co","bugs":{"url":"https://github.com/master-co/css/issues"},"repository":{"type":"git","url":"https://github.com/master-co/css.git","directory":"packages/server"},"keywords":["server","static","html","markup","dom","css","mastercss"],"sideEffects":false,"main":"./dist/index.mjs","module":"./dist/index.mjs","jsnext:main":"./dist/index.mjs","esnext":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","default":"./dist/index.mjs"}},"files":["dist"],"publishConfig":{"access":"public","provenance":true},"dependencies":{"@master/css":"^2.0.0-rc.70","@master/css-preset":"^2.0.0-rc.70","@master/css-validator":"^2.0.0-rc.70","dom-serializer":"^3.1.1","domhandler":"^6.0.1","htmlparser2":"^12.0.0","@master/css-schema":"^2.0.0-rc.70"},"devDependencies":{"@master/css-compiler":"^2.0.0-rc.70"},"version":"2.0.0-rc.70"}

package/dist/decode-html.cjs

@@ -1,29 +0,0 @@
-'use strict';
-
-/*
- * The framework will encode attribute values ​​when rendering HTML to prevent XSS,
- * so we must decode it for correct CSS selectors.
- * https://github.com/facebook/react/issues/27836
- */ function decodeHTML(html) {
-    return html.replace(/&(amp|apos|#39|#x27|quot|lt|gt);/g, (match, entity)=>{
-        switch(entity){
-            case 'amp':
-                return '&';
-            case 'apos':
-            case '#39':
-            case '#x27':
-                return '\'';
-            case 'quot':
-                return '"';
-            case 'lt':
-                return '<';
-            case 'gt':
-                return '>';
-            default:
-                return match // 如果不是已知的實體，保留原樣
-                ;
-        }
-    });
-}
-
-module.exports = decodeHTML;

package/dist/index.cjs

@@ -1,11 +0,0 @@
-'use strict';
-
-var render = require('./render.cjs');
-var renderCss = require('./render-css.cjs');
-var parseHtml = require('./parse-html.cjs');
-
-
-
-exports.render = render;
-exports.renderCSS = renderCss;
-exports.parseHTML = parseHtml;

package/dist/parse-html.cjs

@@ -1,46 +0,0 @@
-'use strict';
-
-var htmlparser2 = require('htmlparser2');
-var decodeHtml = require('./decode-html.cjs');
-
-/**
- * @param html
- * @returns {classes from html, root element}
- */ function parseHTML(html) {
-    const classes = [];
-    let htmlElement = null;
-    let headElement = null;
-    let styleElement = null;
-    const handler = new htmlparser2.DomHandler(undefined, {}, (element)=>{
-        if (element.type === 'tag') {
-            switch(element.name){
-                case 'html':
-                    htmlElement = element;
-                    break;
-                case 'head':
-                    headElement = element;
-                    break;
-            }
-        } else if (element.type === 'style') {
-            if (element.attribs.id === 'master') styleElement = element;
-        }
-        if (element.attribs.class) {
-            element.attribs.class.split(' ').forEach((className)=>{
-                className = decodeHtml(className);
-                if (!classes.includes(className)) classes.push(className);
-            });
-        }
-    });
-    new htmlparser2.Parser(handler, {
-        decodeEntities: false
-    }).end(html);
-    return {
-        classes,
-        nodes: handler.root.childNodes,
-        htmlElement,
-        headElement,
-        styleElement
-    };
-}
-
-module.exports = parseHTML;

package/dist/render-css.cjs

@@ -1,20 +0,0 @@
-'use strict';
-
-var parseHtml = require('./parse-html.cjs');
-var css = require('@master/css');
-
-/**
- * Renders the Master CSS string from HTML
- * @param html
- * @param config
- * @returns MasterCSS
- */ function renderCSS(html, config) {
-    if (!html) return;
-    const { classes } = parseHtml(html);
-    if (!classes.length) return;
-    const css$1 = css.createCSS(config);
-    classes.forEach((eachClass)=>css$1.add(eachClass));
-    return css$1;
-}
-
-module.exports = renderCSS;

package/dist/render.cjs

@@ -1,63 +0,0 @@
-'use strict';
-
-var css = require('@master/css');
-var parseHtml = require('./parse-html.cjs');
-var domhandler = require('domhandler');
-var serialize = require('dom-serializer');
-
-/**
- * Renders the page-required and sorted CSS text from HTML and injected it back into HTML
- * @param html
- * @param config
- */ function render(html, config) {
-    const context = parseHtml(html);
-    const { classes, nodes, htmlElement } = context;
-    let { headElement, styleElement } = context;
-    if (!classes.length) return {
-        html,
-        classes,
-        nodes,
-        htmlElement,
-        headElement,
-        styleElement
-    };
-    const css$1 = css.createCSS(config);
-    classes.forEach((eachClass)=>css$1.add(eachClass));
-    if (styleElement) {
-        styleElement.childNodes = [
-            new domhandler.Text(css$1.text)
-        ];
-    } else {
-        styleElement = new domhandler.Element('style', {
-            id: 'master'
-        }, [
-            new domhandler.Text(css$1.text)
-        ]);
-        if (headElement) {
-            headElement.childNodes.push(styleElement);
-        } else {
-            if (htmlElement) {
-                headElement = new domhandler.Element('head', {}, [
-                    styleElement
-                ]);
-                htmlElement.childNodes.unshift(headElement);
-            } else {
-                nodes.unshift(styleElement);
-            }
-        }
-    }
-    return {
-        html: serialize(nodes, {
-            decodeEntities: false,
-            encodeEntities: false
-        }),
-        css: css$1,
-        classes,
-        nodes,
-        htmlElement,
-        headElement,
-        styleElement
-    };
-}
-
-module.exports = render;