@ecomcx/ecomweb-content 0.0.0-stage → 1.15.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ecomcx JSC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,179 @@
-# Temporary Holding Version
+# @ecomcx/ecomweb-content — định dạng nội dung của CMS
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Chuẩn lưu nội dung bài viết/trang của CMS, **không phụ thuộc trình soạn**. Trình soạn (hiện là TipTap/ProseMirror trong `@ecomcx/ecomweb-editor`) chuyển sang chuẩn này; website (`@ecomcx/ecomweb-theme-sdk`) và máy chủ (`ContentFormat.cs`) chỉ đọc chuẩn này. Đổi hay thay trình soạn không đổi dữ liệu đã lưu, website vẫn chạy.
+
+CMS lưu **dữ liệu**, HTML vẽ lúc hiển thị → theme đổi giao diện khối thì bài cũ tự theo, không có HTML cũ lệch với mã mới.
+
+## Định dạng (bản 1)
+
+```jsonc
+{
+  "version": 1,
+  "blocks": [
+    { "id": "main", "type": "richtext", "data": { "type": "doc", "content": [ /* RichNode */ ] } },
+    { "id": "b2", "type": "html", "data": { "html": "<p>nội dung nhập từ hệ thống cũ</p>" } },
+    { "id": "b3", "type": "ecommerce/products", "data": { "ids": [1, 2] } }   // khối của plugin
+  ]
+}
+```
+
+**RichNode** — cây nội dung soạn thảo:
+
+```jsonc
+{ "type": "paragraph", "attrs": { "textAlign": "center" }, "content": [
+  { "type": "text", "text": "Xin chào ", "marks": [{ "type": "bold" }] },
+  { "type": "text", "text": "liên kết", "marks": [{ "type": "link", "attrs": { "href": "https://…" } }] }
+] }
+```
+
+- Khối lõi và thuộc tính: `CORE_NODES`, `CORE_MARKS` trong `src/schema.ts` (1.9: mục lục `tableOfContents`, ảnh bìa `cover`, nhiều nút `buttons` > `button`, khoảng trống `spacer`, ảnh + chữ `mediaText`, trích dẫn nổi bật `pullquote`, chi tiết `details`, HTML tuỳ chỉnh `customHtml` (máy chủ lọc khi người soạn thiếu quyền `unfiltered_html`), mạng xã hội `socialLinks`, văn bản định dạng sẵn `preformatted`; đoạn, tiêu đề, danh sách, danh sách việc, trích dẫn, mã, ảnh, bộ ảnh, video, âm thanh, tệp, bảng, YouTube; từ 1.2: cột `columns` > `column`, nhóm `group`, hộp lưu ý `callout`, nút `button`, nhúng `embed`; đậm, nghiêng, gạch chân, gạch ngang, mã, chỉ số trên/dưới, tô nền, màu chữ, liên kết).
+- `null` = không có: thuộc tính null không được lưu. Thuộc tính khối lõi sai kiểu được ép (`"3"` → `3`, kẹp min/max) hoặc bỏ.
+- **Khối / nút lạ được giữ nguyên** (khối của plugin, kể cả khi plugin đã tắt) — website bỏ qua khối không có renderer, nút lạ trong nội dung soạn thảo vẫn hiện phần chữ bên trong.
+- Giới hạn: lồng tối đa 64 cấp, tối đa 100 000 nút một bài.
+- `version` tăng khi đổi cấu trúc, kèm hàm nâng cấp (`src/migrate.ts`) — bài lưu bằng bản cũ được nâng khi đọc.
+
+## Khối động (1.6)
+
+Khối không chứa chữ cố định — lấy dữ liệu lúc hiển thị theo ngữ cảnh (dùng trong template của theme / Trình dựng, hoặc trang dựng bằng khối). Danh sách: `DYNAMIC_NODES`.
+
+| Nhóm | Khối | Thuộc tính |
+|---|---|---|
+| Website | `siteTitle`, `siteLogo`, `siteTagline`, `navigation`, `search`, `languageSwitcher`, `copyright` | `level`, `link`, `width`, `location` (vị trí menu), `orientation`, `mobile`, `placeholder`, `buttonText`, `text`, `textAlign` |
+| Bài / trang đang xem (hoặc bài trong vòng lặp) | `postTitle`, `postContent`, `postExcerpt`, `featuredImage`, `postDate`, `postAuthor`, `postTerms`, `comments` | `level`, `link`, `moreText`, `size`, `aspect`, `avatar`, `taxonomy`, `separator` |
+| Danh sách bài | `query` > `postTemplate` (khuôn lặp cho từng bài) + `pagination` + `queryEmpty` | `inherit` (dùng danh sách của trang đang xem), `postType`, `perPage`, `category`, `tag`, `orderBy`, `order`; `layout` (`list`/`grid`), `columns` |
+| Ghép | `templatePart` | `slug` (vd `header`, `footer`), `tagName` |
+| Mẫu đồng bộ | `syncedPattern` | `ref` (id của mẫu — sửa mẫu gốc thì mọi chỗ dùng đổi theo) |
+
+## Kiểu dáng khối (1.7) — `attrs.style`
+
+Mọi khối (lõi và plugin) có thể mang `attrs.style`:
+
+```jsonc
+"style": {
+  "padding": { "base": "xl", "tablet": "lg", "mobile": { "top": "md", "bottom": "md" } },   // tablet ≤ 1024px, mobile ≤ 640px
+  "margin": { "base": "auto" }, "gap": { "base": "lg" }, "width": { "base": "100%" }, "maxWidth": { "base": "640px" },
+  "minHeight": { "base": "60vh" }, "fontFamily": "heading",
+  "fontSize": { "base": "3xl", "mobile": "2xl" }, "lineHeight": { "base": 1.2 }, "letterSpacing": { "base": "0.05em" },
+  "fontWeight": "700", "fontStyle": "italic", "textDecoration": "underline", "textTransform": "uppercase", "textAlign": { "base": "center" },
+  "color": { "text": "white", "background": "#0f172a" }, "border": { "width": "1px", "style": "dashed", "color": "primary" }, "radius": "12px",
+  "hide": ["mobile"]
+}
+```
+
+- Giá trị: preset của theme (`lg`, `2xl`, `primary` → `var(--ecx-spacing-lg)`, `var(--ecx-font-size-2xl)`, `var(--ecx-color-primary, primary)`) hoặc giá trị CSS đã kiểm (độ dài `px|rem|em|%|vw|vh`, `0`, `auto`, màu hex/rgb/hsl). Giá trị khác bị bỏ khi chuẩn hoá → không chèn được CSS.
+- Một giá trị gọn (`"padding": "lg"`) được chuẩn hoá thành `{ "base": "lg" }`.
+- `styleClass(style)` → class ổn định (`ecx-s-…`), `styleCss(style)` → CSS (`.cls.cls{…}` + media query), `collectStyles([...])` gom CSS cả trang. Website và trình soạn dùng chung.
+- `fontFamily` chỉ nhận tên preset (`body`, `heading`, `mono`… → `var(--ecx-font-family-heading, inherit)`), theme khai báo phông.
+- Preset mặc định nằm trong `style.css` (`--ecx-spacing-xs…3xl`, `--ecx-font-size-xs…4xl`, `--ecx-color-primary|muted|surface|white|black`); theme đặt lại biến để đổi.
+
+## Biến thể kiểu, neo, class riêng (1.10)
+
+Mọi khối có thể mang `attrs.blockStyle` (tên biến thể → class `ecx-is-<tên>`), `attrs.anchor` (id để làm neo, vd `#bang-gia`), `attrs.className` (tối đa 5 class CSS hợp lệ). Biến thể có sẵn của lõi (`CORE_BLOCK_STYLES`, CSS trong `style.css`): bảng `stripes`; ảnh `rounded`, `circle`; trích dẫn `plain`; đường kẻ `dots`, `wide`; nút `pill`; nhóm `card`. Theme thêm biến thể bằng `theme.json › blockStyles` và CSS `.ecx-is-<tên>`.
+
+## Preset toàn site (1.10)
+
+`theme.json › styles` (`colors`, `fontSizes`, `spacing`, `fonts`) + bản sửa của quản trị viên → `mergePresets(theme, user)` → `presetCss()` sinh `:root{--ecx-color-*;--ecx-font-size-*;--ecx-spacing-*;--ecx-font-family-*}`. Giá trị được kiểm: màu hex/rgb/hsl, độ dài hoặc `clamp()`, danh sách phông không có `; { }`.
+
+## Bố cục, hiệu ứng, Global Styles (1.15)
+
+Thêm vào `attrs.style`:
+
+```json
+{
+  "layout": { "type": "flex", "direction": { "base": "row", "mobile": "column" }, "justify": "between", "align": "center", "wrap": true },
+  "layout": { "type": "grid", "columns": { "base": 3, "tablet": 2, "mobile": 1 }, "minColumnWidth": "14rem" },
+  "gradient": "linear-gradient(135deg, #1a597b 0%, #f26251 100%)",
+  "shadow": "md", "aspectRatio": "16/9", "position": { "type": "sticky", "top": "md" },
+  "hover": { "color": { "text": "#fff", "background": "primary" }, "border": { "color": "accent" }, "shadow": "lg", "lift": true }
+}
+```
+
+- `layout`: `flex` (hàng ngang / xếp dọc — `direction`, `justify` start|center|end|between, `align` start|center|end|stretch, `wrap`) hoặc `grid` (`columns` 1–12 theo khổ, không có thì tự chia cột theo `minColumnWidth`). Không đặt `gap` thì dùng `--ecx-block-gap` (mặc định 1rem).
+- `gradient`: preset (`brand` → `var(--ecx-gradient-brand)`) hoặc `linear-gradient` / `radial-gradient` với 2–6 điểm màu hex/rgb/hsl (kèm %) — mọi phần được kiểm, không chèn được CSS.
+- `shadow`: preset (`sm` `md` `lg` `xl` có sẵn giá trị dự phòng, theme ghi đè) hoặc `none`. `aspectRatio`: `1/1` `4/3` `3/2` `16/9` `21/9` `3/4` `2/3` `9/16`.
+- `hover` → `:hover` kèm chuyển động. `ruleCss(selector, style)` sinh CSS cho bộ chọn bất kỳ (website, trình soạn, Global Styles).
+
+Preset có thêm `gradients`, `shadows` (tối đa 3 lớp bóng đã kiểm) và **Global Styles**: `blocks` (kiểu mặc định theo loại khối — `BLOCK_SELECTORS`) và `elements` (`link`, `button`, `heading`, `h1`–`h6`, `caption` — `ELEMENT_SELECTORS`). `presetCss` sinh luật trong `:where(.ecx-content)` (độ ưu tiên thấp: kiểu riêng của từng khối luôn thắng). Máy chủ chạy cùng quy tắc (`StyleFormat.cs`, fixture `style-layout-effects`).
+
+## Nhúng theo đường dẫn — `embedInfo`
+
+Khối `embed` chỉ lưu `url` (+ `caption`). `embedInfo(url)` nhận ra nhà cung cấp trong danh sách (YouTube, Vimeo, Loom, Spotify, SoundCloud, TikTok, X, Instagram, Facebook video, CodePen, Figma, Google Maps dạng embed) và **tự dựng** địa chỉ khung từ mã trong đường dẫn — không dùng HTML nhúng do người dùng dán, nên bài viết không chèn được khung tới trang tuỳ ý. Không nhận ra → `null`, website hiện liên kết thường. Trình soạn (xem trước) và website dùng chung hàm này.
+
+## Cài
+
+```bash
+npm install github:Ecomcx-Jsc/ecomweb-content#semver:^1
+```
+
+```json
+"dependencies": { "@ecomcx/ecomweb-content": "github:Ecomcx-Jsc/ecomweb-content#semver:^1" }
+```
+
+`#semver:^1` = mọi bản 1.x (tag `v1.*`): `npm update @ecomcx/ecomweb-content` lấy bản mới nhất, bản 2.0 (đổi làm vỡ API) phải chủ động đổi. `package-lock.json` ghi đúng commit đã cài. `dist/` được commit sẵn trong repo (npm 11 bỏ qua `prepare` của gói GitHub khi cài với `--ignore-scripts` — Builder của CMS cài như vậy). Không phụ thuộc thư viện nào lúc chạy — dùng được trong trình duyệt, Node, Next.js, công cụ dòng lệnh.
+
+## Dùng
+
+```ts
+import { normalizeContent, contentText, wordCount, isSafeUrl } from "@ecomcx/ecomweb-content";
+
+const { doc, issues } = normalizeContent(input);   // {version, blocks}, cây TipTap thuần hoặc chuỗi HTML
+contentText(doc);                                  // chữ thuần (tìm kiếm, tóm tắt)
+```
+
+## Giao diện nền — `style.css`
+
+```ts
+import "@ecomcx/ecomweb-content/style.css";
+```
+
+CSS tối thiểu cho nội dung nằm trong phần tử có class `ecx-content` (bảng có viền, danh sách, trích dẫn, mã, ảnh, chú thích, khung nhúng, khối bố cục) và form `ecx-form`. Website (`PostContent`) và trình soạn (`@ecomcx/ecomweb-editor`) cùng nạp file này → theme không viết CSS cho nội dung vẫn hiển thị đúng, trình soạn và website giống nhau.
+
+- Nằm trong `@layer ecx-content`, mọi selector trong `:where()` → CSS của theme luôn thắng, kể cả CSS có layer (Tailwind). Nạp file này **trước** CSS của theme. Ứng dụng có sẵn layer (vd Tailwind trong admin) mà muốn nền thắng reset của mình thì khai báo `@layer ecx-content;` sau các layer đó.
+- Đổi màu bằng biến: `--ecx-border`, `--ecx-muted`, `--ecx-accent` (mặc định `--primary`), `--ecx-surface`, `--ecx-code-bg`, `--ecx-code-fg`, `--ecx-button-bg`, `--ecx-button-fg`. Không đặt thì màu suy ra từ màu chữ (`currentColor`) → hợp cả nền sáng lẫn tối.
+- Class của khối có tiền tố `ecx-` (`ecx-table`, `ecx-columns`, `ecx-callout`, `ecx-button`, `ecx-embed`, `ecx-align-left`…). Website vẫn xuất kèm class cũ `cms-*` / `table-wrap` / `alignleft` tới bản 2.0.
+- `ecx-full-width` (template trang "full-width" của theme-sdk): trải hết chiều ngang màn hình dù nằm trong khung giới hạn của theme.
+
+## Khối của plugin — `defineBlock`
+
+Khai báo một lần, dùng ở cả trình soạn (admin) lẫn website — đặt trong file dùng chung của plugin: Tên khối luôn có dạng `slug-plugin/tên` — tên không có `/` dành cho khối lõi (khối lõi mới có thể được thêm ở bản 1.x).
+
+```ts
+// blocks.ts
+import { defineBlock } from "@ecomcx/ecomweb-content";
+export const callout = defineBlock({
+  name: "lien-he/callout", title: "Hộp lưu ý", icon: "info", keywords: "luu y callout", content: "blocks",
+  attributes: {
+    tone: { type: "string", enum: ["info", "warning"], enumLabels: ["Thông tin", "Cảnh báo"], default: "info", label: "Kiểu" },
+    title: { type: "string", label: "Tiêu đề" },
+  },
+});
+```
+
+- Admin (`@ecomcx/ecomweb-admin-sdk`): `registerBlock(callout)` → trình soạn tự có mục slash menu, khung khối, form cài đặt sinh từ `attributes` (không viết TipTap).
+- Website (`@ecomcx/ecomweb-theme-sdk`): `definePlugin({ blocks: { [callout.name]: Callout }, blockTypes: [callout] })` — `Callout` nhận `data` (thuộc tính đã chuẩn hoá) và `children` (nội dung bên trong).
+- `content`: `"none"` (khối nguyên), `"inline"` (một dòng chữ), `"blocks"` (chứa khối khác).
+- Đổi cấu trúc thuộc tính: tăng `version`, thêm `migrate[bản-cũ]` — bài đã lưu được nâng khi đọc (lưu kèm `_v`). Migrate lỗi → giữ nguyên dữ liệu.
+- Plugin tắt / gỡ: dữ liệu khối nằm nguyên trong bài; website hiện phần chữ bên trong (nếu có), bật lại là hiện như cũ.
+
+## Hợp đồng
+
+`fixtures/*.json` — mỗi file `{ name, note, input, expected }`. Ba bên cùng chạy bộ này:
+
+| Bên | Test |
+|---|---|
+| `@ecomcx/ecomweb-content` | `normalizeContent(input) == expected`, chuẩn hoá lần hai không đổi |
+| Máy chủ (core) | `ContentFormatTests` — cùng fixture (bản chép ở `backend/tests/Cms.Tests/ContentFixtures/` của repo core) |
+| Website (`@ecomcx/ecomweb-theme-sdk`) | vẽ mỗi fixture ra đúng HTML đã duyệt (`test/snapshots/`) |
+| Trình soạn (`@ecomcx/ecomweb-editor`) | mở fixture rồi xuất lại → chuẩn hoá ra đúng `expected` |
+
+Đổi quy tắc: sửa `src/` + `ContentFormat.cs` + fixture cùng lúc. Thay trình soạn: chỉ cần qua bộ test của trình soạn.
+
+## Phát triển
+
+```bash
+npm install
+npm test        # biên dịch + node --test
+npm run build   # dist/ — commit cùng src/ (npm test báo lỗi nếu dist/ cũ)
+```
+
+Phát hành: tăng `version` (MAJOR.MINOR.PATCH — chỉ tăng MAJOR khi làm vỡ API), commit, `git tag vX.Y.Z && git push --tags`; bên dùng chạy `npm update @ecomcx/ecomweb-content`.

package/dist/bindings.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Gắn dữ liệu (1.15): `attrs.bindings` — thuộc tính của khối lấy giá trị từ một nguồn lúc hiển thị (tiêu đề bài, trường meta,
+ * thuộc tính sản phẩm của plugin…) thay vì chữ gõ tay: `{ content: { source: "core/post", args: { field: "title" } } }`.
+ * Khoá khối: `attrs.lock` `{ move, remove }`, `attrs.templateLock` của khối chứa. Máy chủ chạy cùng quy tắc (ContentFormat.cs).
+ */
+export interface Binding {
+    /** Tên nguồn "nhóm/tên" (core/post, core/post-meta, core/site, tên-plugin/nguồn). */
+    source: string;
+    args?: Record<string, string | number | boolean>;
+}
+/** Chuẩn hoá `attrs.bindings`: tối đa 10 thuộc tính, nguồn đúng dạng, tham số là chữ (≤ 200 ký tự) / số / đúng-sai. */
+export declare function normalizeBindings(v: unknown): Record<string, Binding> | undefined;
+/** `attrs.lock`: chỉ giữ cờ bật. */
+export declare function normalizeLock(v: unknown): {
+    move?: true;
+    remove?: true;
+} | undefined;
+/** `attrs.templateLock` của khối chứa: all | insert | contentOnly | none (khối con thoát khoá của khối ngoài). */
+export declare function normalizeTemplateLock(v: unknown): "all" | "insert" | "contentOnly" | "none" | undefined;

package/dist/bindings.js

@@ -0,0 +1,44 @@
+const SOURCE = /^[a-z0-9-]{1,40}\/[a-z0-9-]{1,40}$/;
+const KEY = /^[a-zA-Z][a-zA-Z0-9]{0,29}$/;
+const ARG_KEY = /^[a-zA-Z][\w-]{0,39}$/;
+const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+/** Chuẩn hoá `attrs.bindings`: tối đa 10 thuộc tính, nguồn đúng dạng, tham số là chữ (≤ 200 ký tự) / số / đúng-sai. */
+export function normalizeBindings(v) {
+    if (!isObj(v))
+        return undefined;
+    const out = {};
+    for (const [k, b] of Object.entries(v)) {
+        if (Object.keys(out).length >= 10)
+            break;
+        if (!KEY.test(k) || !isObj(b) || typeof b.source !== "string" || !SOURCE.test(b.source))
+            continue;
+        const args = {};
+        if (isObj(b.args)) {
+            for (const [ak, av] of Object.entries(b.args)) {
+                if (Object.keys(args).length >= 10)
+                    break;
+                if (!ARG_KEY.test(ak))
+                    continue;
+                if ((typeof av === "string" && av.length <= 200) || (typeof av === "number" && Number.isFinite(av)) || typeof av === "boolean")
+                    args[ak] = av;
+            }
+        }
+        out[k] = Object.keys(args).length ? { source: b.source, args } : { source: b.source };
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+/** `attrs.lock`: chỉ giữ cờ bật. */
+export function normalizeLock(v) {
+    if (!isObj(v))
+        return undefined;
+    const out = {};
+    if (v.move === true)
+        out.move = true;
+    if (v.remove === true)
+        out.remove = true;
+    return Object.keys(out).length ? out : undefined;
+}
+/** `attrs.templateLock` của khối chứa: all | insert | contentOnly | none (khối con thoát khoá của khối ngoài). */
+export function normalizeTemplateLock(v) {
+    return v === "all" || v === "insert" || v === "contentOnly" || v === "none" ? v : undefined;
+}

package/dist/block.d.ts

@@ -0,0 +1,58 @@
+import type { AttrSpec, NodeSpec } from "./schema.js";
+/**
+ * Cách nhập một thuộc tính trong form cài đặt của khối (trình soạn tự sinh form). Mặc định suy từ kiểu:
+ * string → text (có enum → select), number/integer → number, boolean → checkbox, url → url.
+ */
+export type AttrControl = "text" | "textarea" | "number" | "checkbox" | "select" | "color" | "url" | "media" | "hidden";
+export interface BlockAttrSpec extends AttrSpec {
+    /** Nhãn trong form cài đặt (chữ hoặc "%khoá%" dịch theo locales của plugin). */
+    label?: string;
+    control?: AttrControl;
+    /** Nhãn cho từng giá trị của enum (cùng thứ tự). */
+    enumLabels?: readonly string[];
+    help?: string;
+}
+/** Khối chứa gì: không gì (khối nguyên — ảnh, thẻ sản phẩm), chữ (một dòng có định dạng), hoặc các khối khác (hộp lưu ý chứa đoạn văn). */
+export type BlockContent = "none" | "inline" | "blocks";
+export interface BlockDefinitionInput {
+    /** Tên khối, duy nhất trong mọi plugin — nên đặt tiền tố plugin: "ten-plugin/callout" hoặc "tenPluginCallout". */
+    name: string;
+    /** Tên hiển thị (slash menu, khung khối). */
+    title: string;
+    description?: string;
+    /** Biểu tượng (tên icon lucide, vd "star") — trình soạn hiển thị nếu có. */
+    icon?: string;
+    /** Từ khoá tìm trong slash menu (không dấu, cách nhau bởi khoảng trắng). */
+    keywords?: string;
+    category?: string;
+    content?: BlockContent;
+    attributes?: Record<string, BlockAttrSpec>;
+    /**
+     * Phiên bản cấu trúc thuộc tính (mặc định 1). Đổi cấu trúc → tăng version + thêm migrate[phiên-bản-cũ]:
+     * bài lưu bằng bản cũ được nâng khi đọc (trình soạn, website, máy chủ đều đọc qua normalizeContent).
+     */
+    version?: number;
+    migrate?: Record<number, (attrs: Record<string, unknown>) => Record<string, unknown>>;
+}
+export interface BlockDefinition extends Required<Pick<BlockDefinitionInput, "name" | "title" | "content" | "version">> {
+    description?: string;
+    icon?: string;
+    keywords: string;
+    category?: string;
+    attributes: Record<string, BlockAttrSpec>;
+    migrate: Record<number, (attrs: Record<string, unknown>) => Record<string, unknown>>;
+}
+/** Thuộc tính lưu phiên bản của khối trong dữ liệu (chỉ khi version > 1). */
+export declare const BLOCK_VERSION_ATTR = "_v";
+/**
+ * Khai báo một khối — dùng chung cho trình soạn (admin) và website: cùng một file định nghĩa, import ở cả hai phía.
+ * Chỉ là dữ liệu (không phụ thuộc trình soạn nào): trình soạn tự sinh node + form cài đặt + mục slash menu, website
+ * chuẩn hoá thuộc tính rồi đưa cho component hiển thị của plugin. Khối của plugin đã tắt: dữ liệu giữ nguyên.
+ */
+export declare function defineBlock(input: BlockDefinitionInput): BlockDefinition;
+/** Giá trị mặc định của các thuộc tính (khi chèn khối mới). */
+export declare function blockDefaults(def: BlockDefinition): Record<string, unknown>;
+/** Mô tả thuộc tính để chuẩn hoá (normalizeContent → options.nodes). */
+export declare function blockNodeSpec(def: BlockDefinition): NodeSpec;
+/** Nâng thuộc tính của một khối lưu bằng bản cũ lên bản hiện tại. */
+export declare function migrateBlockAttrs(def: BlockDefinition, attrs: Record<string, unknown> | undefined): Record<string, unknown> | undefined;

package/dist/block.js

@@ -0,0 +1,60 @@
+/** Thuộc tính lưu phiên bản của khối trong dữ liệu (chỉ khi version > 1). */
+export const BLOCK_VERSION_ATTR = "_v";
+const NAME = /^[a-zA-Z][\w-]*(\/[a-zA-Z][\w-]*)?$/;
+/**
+ * Khai báo một khối — dùng chung cho trình soạn (admin) và website: cùng một file định nghĩa, import ở cả hai phía.
+ * Chỉ là dữ liệu (không phụ thuộc trình soạn nào): trình soạn tự sinh node + form cài đặt + mục slash menu, website
+ * chuẩn hoá thuộc tính rồi đưa cho component hiển thị của plugin. Khối của plugin đã tắt: dữ liệu giữ nguyên.
+ */
+export function defineBlock(input) {
+    if (!NAME.test(input.name))
+        throw new Error(`defineBlock: tên khối không hợp lệ "${input.name}" (chữ, số, -, _; tuỳ chọn tiền tố "plugin/")`);
+    const version = input.version ?? 1;
+    if (!Number.isInteger(version) || version < 1)
+        throw new Error(`defineBlock(${input.name}): version phải là số nguyên ≥ 1`);
+    for (let v = 1; v < version; v++)
+        if (!input.migrate?.[v])
+            throw new Error(`defineBlock(${input.name}): thiếu migrate[${v}] (nâng từ bản ${v} lên ${v + 1})`);
+    if (input.attributes?.[BLOCK_VERSION_ATTR])
+        throw new Error(`defineBlock(${input.name}): "${BLOCK_VERSION_ATTR}" là tên dành riêng`);
+    return Object.freeze({
+        name: input.name,
+        title: input.title,
+        description: input.description,
+        icon: input.icon,
+        keywords: input.keywords ?? "",
+        category: input.category,
+        content: input.content ?? "none",
+        attributes: { ...input.attributes },
+        version,
+        migrate: { ...input.migrate },
+    });
+}
+/** Giá trị mặc định của các thuộc tính (khi chèn khối mới). */
+export function blockDefaults(def) {
+    const out = {};
+    for (const [k, spec] of Object.entries(def.attributes))
+        if (spec.default !== undefined)
+            out[k] = structuredClone(spec.default);
+    if (def.version > 1)
+        out[BLOCK_VERSION_ATTR] = def.version;
+    return out;
+}
+/** Mô tả thuộc tính để chuẩn hoá (normalizeContent → options.nodes). */
+export function blockNodeSpec(def) {
+    return { attrs: { ...def.attributes, [BLOCK_VERSION_ATTR]: { type: "integer", min: 1 } } };
+}
+/** Nâng thuộc tính của một khối lưu bằng bản cũ lên bản hiện tại. */
+export function migrateBlockAttrs(def, attrs) {
+    if (def.version <= 1)
+        return attrs;
+    let current = { ...(attrs ?? {}) };
+    let v = typeof current[BLOCK_VERSION_ATTR] === "number" ? current[BLOCK_VERSION_ATTR] : 1;
+    if (v >= def.version)
+        return attrs;
+    delete current[BLOCK_VERSION_ATTR];
+    for (; v < def.version; v++)
+        current = def.migrate[v]({ ...current });
+    current[BLOCK_VERSION_ATTR] = def.version;
+    return current;
+}

package/dist/embed.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Nhúng theo đường dẫn (khối `embed`): chỉ nhà cung cấp trong danh sách dưới đây được hiển thị dạng khung nhúng.
+ * Địa chỉ khung luôn do hàm này dựng từ mã nhận ra trong đường dẫn (không dùng HTML/URL nhúng do người dùng dán) →
+ * dữ liệu bài viết không thể chèn khung tới trang tuỳ ý. Đường dẫn không nhận ra → website hiện liên kết thường.
+ * Trình soạn (xem trước) và website (theme-sdk) dùng chung hàm này.
+ */
+export interface EmbedInfo {
+    /** Mã nhà cung cấp (youtube, vimeo…). */
+    provider: string;
+    /** Tên hiển thị (title của iframe). */
+    title: string;
+    /** Địa chỉ khung nhúng. */
+    src: string;
+    /** Tỉ lệ rộng/cao (khung co giãn theo bề ngang). Không có → dùng `height` cố định. */
+    aspect?: number;
+    height?: number;
+    /** Bề ngang tối đa (vd video dọc TikTok). */
+    maxWidth?: number;
+}
+/** Thông tin nhúng của một đường dẫn, hoặc null nếu không thuộc nhà cung cấp nào được hỗ trợ. */
+export declare function embedInfo(raw: unknown): EmbedInfo | null;
+/** Nhà cung cấp được hỗ trợ (để hiện gợi ý trong trình soạn / tài liệu). */
+export declare const EMBED_PROVIDERS: readonly string[];

package/dist/embed.js

@@ -0,0 +1,63 @@
+const UrlCtor = globalThis.URL;
+const enc = encodeURIComponent;
+/** Giây bắt đầu từ ?t=1m30s / ?t=90 / ?start=90. */
+function startSeconds(url) {
+    const t = url.searchParams.get("t") ?? url.searchParams.get("start") ?? "";
+    if (/^\d+$/.test(t))
+        return Number(t);
+    const m = t.match(/^(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$/);
+    return m ? Number(m[1] ?? 0) * 3600 + Number(m[2] ?? 0) * 60 + Number(m[3] ?? 0) : 0;
+}
+const RULES = [
+    { provider: "youtube", title: "YouTube", aspect: 16 / 9,
+        match: /^https:\/\/(?:www\.|m\.)?(?:youtube\.com\/(?:watch\?(?:.*&)?v=|embed\/|shorts\/|live\/)|youtu\.be\/)([\w-]{11})(?:[?&#/]|$)/,
+        src: (m, u) => `https://www.youtube-nocookie.com/embed/${m[1]}${startSeconds(u) ? `?start=${startSeconds(u)}` : ""}` },
+    { provider: "vimeo", title: "Vimeo", aspect: 16 / 9, match: /^https:\/\/(?:www\.)?vimeo\.com\/(?:video\/)?(\d+)(?:[?#/]|$)/, src: (m) => `https://player.vimeo.com/video/${m[1]}?dnt=1` },
+    { provider: "loom", title: "Loom", aspect: 16 / 9, match: /^https:\/\/(?:www\.)?loom\.com\/share\/([a-f0-9]+)(?:[?#]|$)/, src: (m) => `https://www.loom.com/embed/${m[1]}` },
+    { provider: "spotify", title: "Spotify", height: (m) => (m[1] === "track" || m[1] === "episode" ? 152 : 352),
+        match: /^https:\/\/open\.spotify\.com\/(?:intl-[a-z-]+\/)?(track|album|playlist|episode|show|artist)\/([A-Za-z0-9]+)(?:[?#]|$)/, src: (m) => `https://open.spotify.com/embed/${m[1]}/${m[2]}` },
+    { provider: "soundcloud", title: "SoundCloud", height: 166, match: /^https:\/\/(?:www\.)?soundcloud\.com\/[\w-]+\/[\w-]+(?:\/sets\/[\w-]+)?(?:[?#]|$)/,
+        src: (_m, u) => `https://w.soundcloud.com/player/?url=${enc(u.origin + u.pathname)}&visual=false` },
+    { provider: "tiktok", title: "TikTok", aspect: 9 / 16, maxWidth: 340, match: /^https:\/\/(?:www\.)?tiktok\.com\/@[\w.-]+\/video\/(\d+)(?:[?#]|$)/, src: (m) => `https://www.tiktok.com/embed/v2/${m[1]}` },
+    { provider: "x", title: "X (Twitter)", height: 520, maxWidth: 550, match: /^https:\/\/(?:www\.|mobile\.)?(?:twitter|x)\.com\/\w+\/status\/(\d+)(?:[?#/]|$)/,
+        src: (m) => `https://platform.twitter.com/embed/Tweet.html?id=${m[1]}&dnt=true` },
+    { provider: "instagram", title: "Instagram", height: 640, maxWidth: 540, match: /^https:\/\/(?:www\.)?instagram\.com\/(p|reel)\/([\w-]+)(?:[?#/]|$)/, src: (m) => `https://www.instagram.com/${m[1]}/${m[2]}/embed` },
+    { provider: "facebook", title: "Facebook", aspect: 16 / 9, match: /^https:\/\/(?:www\.)?facebook\.com\/[\w.-]+\/videos\/(?:[\w.-]+\/)?(\d+)(?:[?#/]|$)/,
+        src: (_m, u) => `https://www.facebook.com/plugins/video.php?href=${enc(u.origin + u.pathname)}` },
+    { provider: "codepen", title: "CodePen", height: 420, match: /^https:\/\/codepen\.io\/([\w-]+)\/(?:pen|full|details)\/(\w+)(?:[?#/]|$)/, src: (m) => `https://codepen.io/${m[1]}/embed/${m[2]}?default-tab=result` },
+    { provider: "figma", title: "Figma", aspect: 16 / 9, match: /^https:\/\/(?:www\.)?figma\.com\/(?:file|design|proto|board)\/[\w-]+/,
+        src: (_m, u) => `https://www.figma.com/embed?embed_host=cms&url=${enc(u.href)}` },
+    { provider: "googlemaps", title: "Google Maps", aspect: 4 / 3, match: /^https:\/\/(?:www\.)?google\.com\/maps\/embed\?pb=[\w!.%-]+$/, src: (_m, u) => u.href },
+];
+/** Thông tin nhúng của một đường dẫn, hoặc null nếu không thuộc nhà cung cấp nào được hỗ trợ. */
+export function embedInfo(raw) {
+    if (typeof raw !== "string" || raw.length > 2048)
+        return null;
+    let url;
+    try {
+        url = new UrlCtor(raw.trim().replace(/^http:\/\//i, "https://"));
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== "https:")
+        return null;
+    const href = url.href;
+    for (const r of RULES) {
+        const m = href.match(r.match);
+        if (!m)
+            continue;
+        const height = typeof r.height === "function" ? r.height(m) : r.height;
+        const info = { provider: r.provider, title: r.title, src: r.src(m, url) };
+        if (r.aspect)
+            info.aspect = r.aspect;
+        if (height)
+            info.height = height;
+        if (r.maxWidth)
+            info.maxWidth = r.maxWidth;
+        return info;
+    }
+    return null;
+}
+/** Nhà cung cấp được hỗ trợ (để hiện gợi ý trong trình soạn / tài liệu). */
+export const EMBED_PROVIDERS = RULES.map((r) => r.title);

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { CONTENT_VERSION, type Block, type ContentDoc, type RichMark, type RichNode } from "./types.js";
+export { CORE_MARKS, CORE_NODES, DYNAMIC_NODES, coerceAttr, normalizeAttrs, type AttrSpec, type AttrType, type NodeSpec } from "./schema.js";
+export { normalizeContent, type NormalizeOptions, type NormalizeResult } from "./normalize.js";
+export { migrateContent } from "./migrate.js";
+export { contentText, nodeText, visitNodes, wordCount } from "./text.js";
+export { isSafeUrl, safeUrl } from "./url.js";
+export { BLOCK_VERSION_ATTR, blockDefaults, blockNodeSpec, defineBlock, migrateBlockAttrs, type AttrControl, type BlockAttrSpec, type BlockContent, type BlockDefinition, type BlockDefinitionInput } from "./block.js";
+export { EMBED_PROVIDERS, embedInfo, type EmbedInfo } from "./embed.js";
+export { BREAKPOINTS, DEVICES, collectStyles, colorCss, normalizeGradient, normalizeStyle, ruleCss, spacingValue, styleClass, styleCss, type BlockLayout, type BlockStyle, type Box, type Device, type Responsive } from "./style.js";
+export { BLOCK_SELECTORS, CORE_BLOCK_STYLES, ELEMENT_SELECTORS, mergePresets, normalizeAnchor, normalizeBlockStyleName, normalizeClassName, normalizePresets, presetCss, type StylePresets } from "./style.js";
+export { normalizeBindings, normalizeLock, normalizeTemplateLock, type Binding } from "./bindings.js";

package/dist/index.js

@@ -0,0 +1,11 @@
+export { CONTENT_VERSION } from "./types.js";
+export { CORE_MARKS, CORE_NODES, DYNAMIC_NODES, coerceAttr, normalizeAttrs } from "./schema.js";
+export { normalizeContent } from "./normalize.js";
+export { migrateContent } from "./migrate.js";
+export { contentText, nodeText, visitNodes, wordCount } from "./text.js";
+export { isSafeUrl, safeUrl } from "./url.js";
+export { BLOCK_VERSION_ATTR, blockDefaults, blockNodeSpec, defineBlock, migrateBlockAttrs } from "./block.js";
+export { EMBED_PROVIDERS, embedInfo } from "./embed.js";
+export { BREAKPOINTS, DEVICES, collectStyles, colorCss, normalizeGradient, normalizeStyle, ruleCss, spacingValue, styleClass, styleCss } from "./style.js";
+export { BLOCK_SELECTORS, CORE_BLOCK_STYLES, ELEMENT_SELECTORS, mergePresets, normalizeAnchor, normalizeBlockStyleName, normalizeClassName, normalizePresets, presetCss } from "./style.js";
+export { normalizeBindings, normalizeLock, normalizeTemplateLock } from "./bindings.js";

package/dist/migrate.d.ts

@@ -0,0 +1,2 @@
+import { type ContentDoc } from "./types.js";
+export declare function migrateContent(doc: ContentDoc, issues?: string[]): ContentDoc;

package/dist/migrate.js

@@ -0,0 +1,19 @@
+import { CONTENT_VERSION } from "./types.js";
+/**
+ * Nâng định dạng nội dung: MIGRATIONS[n] chuyển bản n → n+1. Bài lưu bằng bản cũ được nâng khi đọc,
+ * nên đổi cấu trúc không làm vỡ bài đã đăng. Chưa có bản nào cần nâng (định dạng 1).
+ */
+const MIGRATIONS = {};
+export function migrateContent(doc, issues = []) {
+    let current = doc;
+    if (current.version > CONTENT_VERSION) {
+        // Nội dung từ bản CMS mới hơn: giữ nguyên, không đoán
+        issues.push(`content version ${current.version} is newer than ${CONTENT_VERSION}`);
+        return current;
+    }
+    while (current.version < CONTENT_VERSION) {
+        const step = MIGRATIONS[current.version];
+        current = step ? step(current) : { ...current, version: current.version + 1 };
+    }
+    return current;
+}

package/dist/normalize.d.ts

@@ -0,0 +1,25 @@
+import { type BlockDefinition } from "./block.js";
+import { type NodeSpec } from "./schema.js";
+import { type ContentDoc } from "./types.js";
+export interface NormalizeOptions {
+    /** Độ sâu lồng tối đa của nội dung soạn thảo (chống nội dung độc làm treo máy). Mặc định 64. */
+    maxDepth?: number;
+    /** Số nút tối đa của một bài. Mặc định 100 000. */
+    maxNodes?: number;
+    /** Khối của plugin (defineBlock): ép kiểu thuộc tính + nâng phiên bản khối lưu bằng bản cũ. */
+    blocks?: readonly BlockDefinition[];
+    /** Mô tả thuộc tính của nút ngoài lõi (cấp thấp — khối plugin dùng `blocks`). */
+    nodes?: Record<string, NodeSpec>;
+    marks?: Record<string, NodeSpec>;
+}
+export interface NormalizeResult {
+    doc: ContentDoc;
+    /** Những gì đã bị sửa/bỏ — để ghi log, không phải lỗi. */
+    issues: string[];
+}
+/**
+ * Chuẩn hoá nội dung về định dạng của CMS. Nhận: {version, blocks}, cây TipTap/ProseMirror thuần (`type: "doc"`),
+ * chuỗi HTML. Sửa cấu trúc sai (bỏ nút không hợp lệ, ép kiểu thuộc tính khối lõi, bỏ null), giữ nguyên khối/nút lạ.
+ * Chạy hai lần cho cùng kết quả (idempotent). Máy chủ chạy cùng quy tắc (ContentFormat.cs).
+ */
+export declare function normalizeContent(input: unknown, options?: NormalizeOptions): NormalizeResult;