px-to-scale 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jscodev
+
+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

@@ -0,0 +1,202 @@
+# Px To Scale Responsive Layout Plugin
+
+English | [中文](./README.zh-CN.md)
+
+Proportional responsive layout made simple: write CSS in px against your design width, and every scoped element scales with the screen width — like viewing the design at different zoom levels.
+
+Works in two cooperating ways, pick per project (or per page):
+
+- **Browser runtime** — computes the current width ratio and keeps it updated on resize
+- **Build-time PostCSS plugin** — rewrites your px values into scale expressions during the build
+
+## Install
+
+```bash
+npm install px-to-scale
+```
+
+CDN (for quick trials, browser runtime only):
+
+```html
+<script src="px-to-scale/lib/px-to-scale.umd.js"></script>
+<script>
+  PxToScale.initBasis(1920, 'c3')
+</script>
+```
+
+## Quick Start (3 steps)
+
+### 1. Initialize in your entry file
+
+```js
+import { initBasis } from 'px-to-scale'
+
+// basis: the design width, e.g. 1920
+// name: a prefix name of your choice, e.g. 'c3'
+initBasis(1920, 'c3')
+```
+
+### 2. Add the PostCSS plugin to your build config
+
+```js
+// vite.config.js
+import { pxToScalePlugin } from 'px-to-scale'
+
+export default defineConfig({
+  css: {
+    postcss: {
+      plugins: [pxToScalePlugin('c3')]
+    }
+  }
+})
+```
+
+The plugin works in any build chain that accepts PostCSS plugins (Vite, webpack postcss-loader, Rollup, etc.).
+
+### 3. Use the prefix class in your markup and styles
+
+```html
+<!-- Elements with the prefix class scale -->
+<div class="c3-container">
+  <div class="c3-box">This box scales with the screen width</div>
+</div>
+
+<!-- Other elements are untouched -->
+<div class="normal-box">This box keeps its size</div>
+```
+
+```css
+/* Write plain px as in the design */
+.c3-box {
+  width: 200px;    /* 200px at 1920px wide, 100px at 960px, 400px at 3840px */
+  height: 100px;
+  font-size: 16px; /* text scales proportionally too */
+}
+```
+
+## What Gets Scaled
+
+A CSS rule is in scope when one of its selectors carries the prefix class — `.c3`, `.c3-anything`, `.c3_anything`:
+
+```css
+.c3-box { width: 200px }        /* in scope */
+.c3-box .inner { width: 40px }  /* in scope: the selector carries the prefix class */
+.other-box { width: 200px }     /* not in scope: stays fixed */
+```
+
+Every px value inside an in-scope rule becomes a scale expression, so all in-scope elements scale together with the screen width. When the runtime is not present, each scale expression falls back to the original px size, so the page never breaks.
+
+Values listed in `excludePxValues` keep their original size. By default that is `1px`, so hairline borders stay crisp at every screen width:
+
+```css
+.c3-box {
+  border: 1px solid #ccc;  /* stays 1px at any width (default exclusion) */
+  width: 200px;            /* scales */
+}
+```
+
+## Scaling CSS Variables
+
+Variables hold fixed px by default. To make a variable scale as well, list it in `cssVarPxMap` — declare it with a px value in a `:root` / `html` rule (or an in-scope rule) and every usage of it scales:
+
+```css
+:root {
+  --card-width: 400px;
+  --card-height: 300px;
+}
+
+.c3-card {
+  width: var(--card-width);   /* scales once --card-width is mapped */
+  height: var(--card-height);
+}
+```
+
+```js
+pxToScalePlugin('c3', {
+  cssVarPxMap: ['--card-width', '--card-height']
+})
+```
+
+Unlike regular values, mapped variables have no px exclusions — the map is an explicit opt-in.
+
+## API Reference
+
+> Px To Scale — proportional responsive layout plugin. Write px against a design width; scoped elements scale with the screen width; browser runtime + build-time PostCSS plugin; zero dependencies. TypeScript type declarations ship with the package.
+
+| API | Description |
+| --- | --- |
+| [initBasis](#initbasis) | Start the browser runtime for one prefix name (recommended entry) |
+| [computeBasis](#computebasis) | Recompute the scale ratio once, manually |
+| [pxToScalePlugin](#pxtoscaleplugin) | Build-time PostCSS plugin |
+
+### initBasis
+
+```js
+const handle = initBasis(basis, name)
+```
+
+Starts the browser runtime for one prefix name: computes the current width ratio, keeps it updated when the window is resized, and cascades the scale variable into every element carrying the prefix class (and its descendants). Call it once at app startup, before rendering.
+
+Repeated calls with the same name share one runtime; every call must eventually call `handle.destroy()` to tear it down (the last one removes it). In a non-browser environment it throws.
+
+| Param | Type | Description |
+| --- | --- | --- |
+| basis | number | Design width in px, e.g. 1920 or 375 |
+| name | string | Prefix name; must match the name given to `pxToScalePlugin` |
+| returns | object | Handle with a `destroy()` method |
+
+### computeBasis
+
+```js
+computeBasis(basis, name)
+```
+
+Recomputes the width ratio once and publishes it. Normally not needed — `initBasis` already updates on resize. Use it when you want manual control over the recalculation moment.
+
+| Param | Type | Description |
+| --- | --- | --- |
+| basis | number | Design width in px |
+| name | string | Prefix name |
+
+### pxToScalePlugin
+
+```js
+pxToScalePlugin(name, options)
+```
+
+Build-time PostCSS plugin. Rewrites px values in scoped rules into scale expressions, and rewrites mapped variable definitions when `cssVarPxMap` is set. It throws at configuration time when `name` is missing or empty.
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| name | string | — | Prefix name; must match the name given to `initBasis` |
+| options.cssVarPxMap | string[] | [] | CSS variables whose px definitions should scale |
+| options.excludePxValues | string[] | ['1px'] | px values that keep their original size |
+| options.excludeClasses | string[] | [] | Class names that never count as the prefix class |
+
+`excludePxValues` entries are px strings (e.g. `'1px'`, `'0.5px'`); a value keeps its size when its absolute number matches, so `-1px` is covered by `'1px'`.
+
+## Errors
+
+Invalid usage throws with a message naming the problem — nothing fails silently:
+
+| Situation | Behavior |
+| --- | --- |
+| `name` missing or empty (plugin or runtime) | Throws |
+| `basis` not a positive number (runtime) | Throws |
+| Browser runtime called in a non-browser environment | Throws |
+
+## Notes & Boundaries
+
+- **One name, both sides**: the prefix name passed to `initBasis` and to `pxToScalePlugin` must be identical.
+- **Width only**: scaling follows the viewport width; the height ratio is ignored.
+- **Scoping is by selector text**: a descendant scales when the CSS rule's selector carries the prefix class — not merely because it sits inside a prefixed element in the DOM.
+- **Precision**: the width ratio is published with 3 decimals, so sizes may differ from the exact design by at most 0.1%.
+- **Build-time plugin covers all your rules**: rules inside `@media` / `@supports` / `@layer` blocks are rewritten as well whenever their selector carries the prefix class.
+
+## Documentation
+
+- **Offline doc bundle**: the "Download doc bundle" button on the doc site home page downloads `px-to-scale-apis.zip` (both READMEs, with the full API reference in English and Chinese); the npm package ships both READMEs
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,202 @@
+# Px To Scale 响应式布局插件
+
+[English](./README.md) | 中文
+
+按屏幕宽度等比缩放的响应式布局方案：按设计稿用 px 写 CSS，指定范围内的元素随屏幕宽度整体缩放——就像以不同缩放级别查看设计稿。
+
+提供两种协作方式，按项目（或按页面）选用：
+
+- **浏览器运行时** —— 计算当前宽度比例，并在窗口尺寸变化时自动更新
+- **构建期 PostCSS 插件** —— 在构建时把 px 值改写为缩放表达式
+
+## 安装
+
+```bash
+npm install px-to-scale
+```
+
+CDN 快速体验（仅浏览器运行时）：
+
+```html
+<script src="px-to-scale/lib/px-to-scale.umd.js"></script>
+<script>
+  PxToScale.initBasis(1920, 'c3')
+</script>
+```
+
+## 快速开始（3 步）
+
+### 1. 在入口文件初始化
+
+```js
+import { initBasis } from 'px-to-scale'
+
+// basis：设计稿宽度，如 1920
+// name：自选的前缀名，如 'c3'
+initBasis(1920, 'c3')
+```
+
+### 2. 在构建配置中添加 PostCSS 插件
+
+```js
+// vite.config.js
+import { pxToScalePlugin } from 'px-to-scale'
+
+export default defineConfig({
+  css: {
+    postcss: {
+      plugins: [pxToScalePlugin('c3')]
+    }
+  }
+})
+```
+
+插件可用于任何接受 PostCSS 插件的构建链（Vite、webpack postcss-loader、Rollup 等）。
+
+### 3. 在结构和样式里使用前缀类名
+
+```html
+<!-- 带前缀类名的元素会缩放 -->
+<div class="c3-container">
+  <div class="c3-box">这个盒子随屏幕宽度缩放</div>
+</div>
+
+<!-- 其他元素不受影响 -->
+<div class="normal-box">这个盒子保持原尺寸</div>
+```
+
+```css
+/* 按设计稿直接写 px */
+.c3-box {
+  width: 200px;    /* 1920px 宽屏显示 200px，960px 显示 100px，3840px 显示 400px */
+  height: 100px;
+  font-size: 16px; /* 文字也等比缩放 */
+}
+```
+
+## 哪些内容会缩放
+
+一条 CSS 规则处于范围内，当且仅当它的选择器之一带有前缀类名——`.c3`、`.c3-任意`、`.c3_任意`：
+
+```css
+.c3-box { width: 200px }        /* 范围内 */
+.c3-box .inner { width: 40px }  /* 范围内：选择器带有前缀类名 */
+.other-box { width: 200px }     /* 范围外：保持固定 */
+```
+
+范围内规则里的每个 px 值都会变成缩放表达式，范围内的元素随屏幕宽度一起缩放。运行时缺席时，每个缩放表达式回退为原始 px 尺寸，页面不会因此坏掉。
+
+列在 `excludePxValues` 里的值保持原尺寸。默认为 `1px`，因此发丝边框在任何屏宽下都保持清晰：
+
+```css
+.c3-box {
+  border: 1px solid #ccc;  /* 任何屏宽下都是 1px（默认排除） */
+  width: 200px;            /* 会缩放 */
+}
+```
+
+## 让 CSS 变量参与缩放
+
+变量默认持有固定的 px。要让某个变量也缩放，把它列入 `cssVarPxMap`——在 `:root` / `html` 规则（或范围内规则）中以 px 声明它，它的所有使用处就会一起缩放：
+
+```css
+:root {
+  --card-width: 400px;
+  --card-height: 300px;
+}
+
+.c3-card {
+  width: var(--card-width);   /* --card-width 被映射后即随缩放 */
+  height: var(--card-height);
+}
+```
+
+```js
+pxToScalePlugin('c3', {
+  cssVarPxMap: ['--card-width', '--card-height']
+})
+```
+
+与普通值不同：被映射的变量不做 px 排除——映射本身就是明确的选入。
+
+## API 参考
+
+> Px To Scale —— 按屏幕宽度等比缩放的响应式布局插件。按设计稿写 px，指定范围内的元素随屏幕宽度缩放；浏览器运行时 + 构建期 PostCSS 插件；零依赖。npm 包随附 TypeScript 类型声明。
+
+| API | 说明 |
+| --- | --- |
+| [initBasis](#initbasis) | 启动某个前缀名的浏览器运行时（推荐入口） |
+| [computeBasis](#computebasis) | 手动重新计算一次缩放比例 |
+| [pxToScalePlugin](#pxtoscaleplugin) | 构建期 PostCSS 插件 |
+
+### initBasis
+
+```js
+const handle = initBasis(basis, name)
+```
+
+启动某个前缀名的浏览器运行时：计算当前宽度比例、窗口尺寸变化时自动更新，并把缩放变量级联到所有带前缀类名的元素（及其后代）。在应用启动、渲染之前调用一次即可。
+
+同名重复调用共享同一运行时；每次调用最终都应调用 `handle.destroy()` 注销（最后一个注销时真正移除）。在非浏览器环境中调用会抛错。
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| basis | number | 设计稿宽度（px），如 1920、375 |
+| name | string | 前缀名；必须与 `pxToScalePlugin` 传入的一致 |
+| 返回值 | object | 带 `destroy()` 方法的句柄 |
+
+### computeBasis
+
+```js
+computeBasis(basis, name)
+```
+
+重新计算一次宽度比例并发布。通常无需调用——`initBasis` 已在窗口变化时自动更新。仅在需要手动控制重算时机时使用。
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| basis | number | 设计稿宽度（px） |
+| name | string | 前缀名 |
+
+### pxToScalePlugin
+
+```js
+pxToScalePlugin(name, options)
+```
+
+构建期 PostCSS 插件。把范围内规则中的 px 值改写为缩放表达式；配置了 `cssVarPxMap` 时改写被映射变量的定义。`name` 缺失或为空时在配置阶段即抛错。
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| name | string | — | 前缀名；必须与 `initBasis` 传入的一致 |
+| options.cssVarPxMap | string[] | [] | 需要随缩放的 CSS 变量（其 px 定义） |
+| options.excludePxValues | string[] | ['1px'] | 保持原尺寸的 px 值 |
+| options.excludeClasses | string[] | [] | 永不算作前缀类的类名 |
+
+`excludePxValues` 的条目是 px 字符串（如 `'1px'`、`'0.5px'`）；按绝对数值匹配，因此 `-1px` 也被 `'1px'` 覆盖。
+
+## 错误
+
+错误用法会抛出指明问题的错误——不会静默失败：
+
+| 情形 | 行为 |
+| --- | --- |
+| `name` 缺失或为空（插件或运行时） | 抛错 |
+| `basis` 不是正数（运行时） | 抛错 |
+| 在非浏览器环境调用浏览器运行时 | 抛错 |
+
+## 注意事项与边界
+
+- **一个名字，两端一致**：传给 `initBasis` 与 `pxToScalePlugin` 的前缀名必须相同。
+- **只看宽度**：缩放跟随视口宽度，忽略高度比例。
+- **按选择器文本划范围**：后代元素缩放取决于其 CSS 规则的选择器是否带前缀类名——并不是「DOM 上嵌在带前缀元素里」就缩放。
+- **精度**：宽度比例以 3 位小数发布，尺寸与设计稿的差异至多 0.1%。
+- **构建期插件覆盖所有规则**：`@media` / `@supports` / `@layer` 块内选择器带前缀类名的规则同样会被改写。
+
+## 文档
+
+- **离线文档包**：文档站首页的 "Download doc bundle" 按钮下载 `px-to-scale-apis.zip`（中英双语 README，含完整 API 参考）；npm 包随附两份 README
+
+## 许可证
+
+MIT

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "px-to-scale",
+  "version": "1.0.0",
+  "title": "Px To Scale",
+  "description": "Proportional responsive layout plugin: scale any element with the screen width, via a browser runtime and a build-time PostCSS plugin",
+  "license": "MIT",
+  "author": "jscodev",
+  "type": "module",
+  "main": "./lib/px-to-scale.umd.cjs",
+  "module": "./lib/px-to-scale.js",
+  "types": "./lib/px-to-scale.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/px-to-scale.d.ts",
+      "import": "./lib/px-to-scale.js",
+      "require": "./lib/px-to-scale.umd.cjs",
+      "default": "./lib/px-to-scale.js"
+    }
+  },
+  "files": [
+    "lib",
+    "README.md",
+    "README.zh-CN.md"
+  ],
+  "keywords": [
+    "responsive",
+    "scale",
+    "postcss",
+    "css",
+    "layout"
+  ],
+  "maintainers": [
+    "jscodev"
+  ],
+  "scripts": {
+    "build:types": "tsc -p tsconfig.json",
+    "build:apis": "node scripts/package-apis.cjs",
+    "build": "npm run build:types && vite build && node scripts/obfuscate.cjs && npm run build:apis",
+    "build:doc": "npm run build:apis && cd doc-site && npm install && npm run build",
+    "dev:doc": "npm run build:apis && cd doc-site && npm run dev",
+    "release": "npm version patch --no-tag-if-no-changes && npm publish"
+  },
+  "devDependencies": {
+    "javascript-obfuscator": "^5.6.0",
+    "typescript": "^5.4.0",
+    "vite": "^5.4.0"
+  }
+}