create-shopify-scss-autofill 0.2.0 → 0.2.1

package/bin/create-scss-kit.mjs

@@ -104,6 +104,7 @@ function makeDefaultConfig() {
     },
     autofill: {
       function: 'r.resp',
+      vwFunction: 'r.vw',
       mobileMax: 850,
       scanDirs: ['src/styles'],
       output: 'src/styles/_responsive-autofill.generated.scss',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-shopify-scss-autofill",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Scaffold scss-kit (SCSS workflow + responsive autofill) for Shopify theme development.",
   "keywords": [
     "shopify",

package/template/tools/scss-kit/README.md

@@ -1,6 +1,6 @@
 # scss-kit（本仓库内置工具）
 
-目的：在 Shopify ThemeKit 开发里实现“写 SCSS（src/styles）→ 编译 CSS（assets）→ theme watch 上传”，并提供一套基于 `r.resp(pc, mobile, desktopType[, mobileType])` 的移动端覆盖自动生成能力。
+目的：在 Shopify ThemeKit 开发里实现“写 SCSS（src/styles）→ 编译 CSS（assets）→ theme watch 上传”，并提供一套基于 `r.resp(pc, mobile, desktopType[, mobileType])` 与 `r.vw(pc, mobile)` 的移动端覆盖自动生成能力。
 
 ## 拷贝接入（新项目）
 
@@ -57,6 +57,67 @@
 - 顶部 `@use "./_responsive-autofill.<page>.generated" as auto;`
 - 底部 `@include auto.responsive_autofill_overrides();`（确保覆盖顺序）
 
+推荐约定：
+
+- 字体/需要下限兜底的值：使用 `r.resp(pc, mobile, desktopType[, mobileType])`
+- 大多数间距（padding/margin/gap）：使用 `r.vw(pc, mobile)`
+
+`r.vw(pc, mobile)` 的行为：
+
+- PC 输出 `min(vw, px)`，例如 `r.vw(40px, 24px)` → `min(2.0833vw, 40px)`
+- 自动生成的移动端覆盖直接输出 `vw`，例如 `3.2vw`
+
+## Responsive 函数目录（完整）
+
+以下函数都定义在 `src/styles/_responsive.scss`（由 `scss-kit` 生成）：
+
+### 业务侧常用（推荐直接调用）
+
+- `r.resp($pc, $mobile, $type, $mobile-type: null)`
+  - 用途：用于“字体/需要下限兜底”的场景。
+  - PC 输出：`clamp_pc($pc, min_px($pc, $type, desktop))`。
+  - Mobile 输出：由自动生成器扫描 `r.resp(...)` 后，在 `@media` 中生成 `clamp_mb(...)` 覆盖。
+  - 第 3/4 参数：第 3 个是 PC type；第 4 个是 mobile type（可省略，省略时沿用第 3 个）。
+  - 示例：`font-size: r.resp(40px, 24px, h1, h2);`
+
+- `r.vw($pc, $mobile)`
+  - 用途：用于“间距/尺寸优先流式”的场景（如 padding/margin/gap/宽高）。
+  - PC 输出：`min(vw, px)`（防止超大屏继续放大）。
+  - Mobile 输出：由自动生成器扫描 `r.vw(...)` 后，在 `@media` 中生成纯 `vw` 覆盖。
+  - 示例：`margin-top: r.vw(40px, 24px);`
+
+### 由 `r.resp` / `r.vw` 间接使用（一般不直接写）
+
+- `r.min_px($mobile, $type, $range: mobile, $override-coef: null)`
+  - 用途：计算 clamp 最小值。
+  - 规则：
+    - 在 `mobile` 且 `type` 属于 `h1/h2/h3/body/small/button-text` 时，走可读性规则（按 375 缩放并套 floor）。
+    - 其他情况按系数表 `coef(type, range)` 计算。
+
+- `r.coef($type, $range: mobile)`
+  - 用途：读取 `coefficients.mobile/desktop` 中对应 type 的系数。
+
+- `r.clamp_pc($pc, $min)`
+  - 用途：生成 PC clamp。
+  - 结构：`clamp($min, calc($pc * var(--px-to-vw)), $pc)`。
+
+- `r.clamp_mb($mobile, $min)`
+  - 用途：生成移动端 clamp。
+  - 结构：`clamp($min, calc($mobile * var(--px-to-vw-mb)), $mobile)`。
+
+- `r.vw_pc($pc)`
+  - 用途：生成 PC 端 `vw` 并带上限。
+  - 结构：`min(calc($pc * var(--px-to-vw)), $pc)`。
+
+- `r.vw_mb($mobile)`
+  - 用途：生成移动端纯 `vw`。
+  - 结构：`calc($mobile * var(--px-to-vw-mb))`。
+
+### 内部工具函数（不建议业务直接使用）
+
+- `_to-px($value)`：把无单位数字转为 `px`。
+- `_to-num($value)`：把 `px` 或无单位数字转为纯数字（其他单位会报错）。
+
 ## CSS 编译（safe mode）
 
 `npm run css:watch` 默认走 safe mode：

package/template/tools/scss-kit/cli.mjs

@@ -67,6 +67,7 @@ function getMobileMax(cfg) {
 
 function getAutofill(cfg) {
   const fn = cfg?.autofill?.function ?? 'r.resp'
+  const vwFn = cfg?.autofill?.vwFunction
   const mobileMax = getMobileMax(cfg)
   const scanDirs = cfg?.autofill?.scanDirs ?? [
     cfg?.paths?.scssSrcDir ?? 'src/styles',
@@ -82,9 +83,27 @@ function getAutofill(cfg) {
   }
   const ns = parts[0]
   const name = parts[1]
+
+  const defaultVwFn = `${ns}.vw`
+  const vwParts = String(vwFn ?? defaultVwFn).split('.')
+  if (vwParts.length !== 2 || !vwParts[0] || !vwParts[1]) {
+    throw new Error(
+      `Invalid autofill.vwFunction: ${String(
+        vwFn
+      )}. Expected format: <ns>.<name> (e.g. ${defaultVwFn})`
+    )
+  }
+  if (vwParts[0] !== ns) {
+    throw new Error(
+      `autofill.vwFunction namespace must match autofill.function namespace (${ns})`
+    )
+  }
+  const vwName = vwParts[1]
+
   return {
     ns,
     name,
+    vwName,
     mobileMax,
     scanDirs,
     outputAbs: path.join(ROOT, output),
@@ -139,8 +158,7 @@ function splitTopLevelArgs(argsStr) {
   return args
 }
 
-function replaceRespCalls(value, { ns, name }) {
-  const token = `${ns}.${name}(`
+function replaceFunctionCalls(value, token, mapArgsToReplacement) {
   let out = ''
   let idx = 0
   let changed = false
@@ -183,11 +201,9 @@ function replaceRespCalls(value, { ns, name }) {
 
     const argsStr = value.slice(argsStart, i)
     const args = splitTopLevelArgs(argsStr)
-    if (args.length >= 3) {
-      const mobile = args[1]
-      const desktopType = args[2]
-      const mobileType = args.length >= 4 ? args[3] : desktopType
-      out += `${ns}.clamp_mb(${mobile}, ${ns}.min_px(${mobile}, ${mobileType}, mobile))`
+    const replacement = mapArgsToReplacement(args)
+    if (replacement != null) {
+      out += replacement
       changed = true
     } else {
       // Not enough args: keep original call.
@@ -200,6 +216,33 @@ function replaceRespCalls(value, { ns, name }) {
   return { value: out.trim(), changed }
 }
 
+function replaceAutofillCalls(value, { ns, name, vwName }) {
+  const respToken = `${ns}.${name}(`
+  const replacedResp = replaceFunctionCalls(value, respToken, (args) => {
+    if (args.length < 3) return null
+    const mobile = args[1]
+    const desktopType = args[2]
+    const mobileType = args.length >= 4 ? args[3] : desktopType
+    return `${ns}.clamp_mb(${mobile}, ${ns}.min_px(${mobile}, ${mobileType}, mobile))`
+  })
+
+  const vwToken = `${ns}.${vwName}(`
+  const replacedVw = replaceFunctionCalls(
+    replacedResp.value,
+    vwToken,
+    (args) => {
+      if (args.length < 2) return null
+      const mobile = args[1]
+      return `${ns}.vw_mb(${mobile})`
+    }
+  )
+
+  return {
+    value: replacedVw.value.trim(),
+    changed: replacedResp.changed || replacedVw.changed,
+  }
+}
+
 function combineSelectors(parents, children) {
   const out = []
   for (const p of parents) {
@@ -216,7 +259,7 @@ function combineSelectors(parents, children) {
   return out
 }
 
-function scanScssForAutofill_legacy(absFilePath, { ns, name }) {
+function scanScssForAutofill_legacy(absFilePath, { ns, name, vwName }) {
   const raw = fs.readFileSync(absFilePath, 'utf8')
   const lines = raw.split(/\r?\n/)
 
@@ -275,7 +318,7 @@ function scanScssForAutofill_legacy(absFilePath, { ns, name }) {
       value = value.replace(/\s!important\s*$/i, '').trim()
     }
 
-    const replaced = replaceRespCalls(value, { ns, name })
+    const replaced = replaceAutofillCalls(value, { ns, name, vwName })
     if (!replaced.changed) continue
 
     const finalValue = important
@@ -290,7 +333,7 @@ function scanScssForAutofill_legacy(absFilePath, { ns, name }) {
   return rules
 }
 
-function scanScssForAutofill_ast(absFilePath, { ns, name }) {
+function scanScssForAutofill_ast(absFilePath, { ns, name, vwName }) {
   // Lazy-load optional deps so `init` can run before `npm install`.
   /** @type {typeof import('postcss')} */
   let postcss
@@ -332,7 +375,7 @@ function scanScssForAutofill_ast(absFilePath, { ns, name }) {
           const property = String(child.prop)
           let value = String(child.value ?? '').trim()
 
-          const replaced = replaceRespCalls(value, { ns, name })
+          const replaced = replaceAutofillCalls(value, { ns, name, vwName })
           if (!replaced.changed) continue
 
           const finalValue = child.important
@@ -362,12 +405,12 @@ function scanScssForAutofill_ast(absFilePath, { ns, name }) {
   return rules
 }
 
-function scanScssForAutofill(absFilePath, { ns, name }) {
+function scanScssForAutofill(absFilePath, { ns, name, vwName }) {
   try {
-    return scanScssForAutofill_ast(absFilePath, { ns, name })
+    return scanScssForAutofill_ast(absFilePath, { ns, name, vwName })
   } catch (e) {
     // Fallback for edge cases where parser can't handle a file.
-    return scanScssForAutofill_legacy(absFilePath, { ns, name })
+    return scanScssForAutofill_legacy(absFilePath, { ns, name, vwName })
   }
 }
 
@@ -388,7 +431,7 @@ function generateAutofillScss(cfg, collectedRules) {
   const header = `@use "./responsive" as ${ns};
 
 // Generated by scss-kit from ${CONFIG_NAME}
-// Source: scanned ${ns}.resp(pc, mobile, type) markers in scss.
+// Source: scanned ${ns}.resp(pc, mobile, desktopType[, mobileType]) and ${ns}.vw(pc, mobile) markers in scss.
 // Do not edit this file directly; re-run: npm run scss-kit:responsive:generate
 \n`
 
@@ -606,6 +649,31 @@ $coef-desktop: ${desktopMap};
   @return clamp(#{$min}, calc(#{$n} * var(--px-to-vw-mb)), #{$v});
 }
 
+// 直接输出 PC 段 vw，并用设计稿 px 做上限兜底。
+@function vw_pc($pc) {
+  $v: _to-px($pc);
+  $n: _to-num($pc);
+  @return min(calc(#{$n} * var(--px-to-vw)), #{$v});
+}
+
+// 直接输出移动段 vw（无 clamp）。
+@function vw_mb($mobile) {
+  $n: _to-num($mobile);
+  @return calc(#{$n} * var(--px-to-vw-mb));
+}
+
+// vw(): spacing-first helper
+// - PC: min(vw, px)
+// - Mobile: pure vw (via autofill overrides)
+// - arg1: pc
+// - arg2: mobile (used by autofill scanner for mobile overrides)
+@function vw($pc, $mobile) {
+  @if meta.type-of($pc) != number or meta.type-of($mobile) != number {
+    @error "vw() expects numeric px values for both pc and mobile";
+  }
+  @return vw_pc($pc);
+}
+
 // resp():
 // - arg3: desktop type
 // - arg4 (optional): mobile type, defaults to desktop type

package/template/tools/scss-kit/schema.json

@@ -25,6 +25,7 @@
       "type": "object",
       "properties": {
         "function": {"type": "string"},
+        "vwFunction": {"type": "string"},
         "mobileMax": {"type": "integer", "minimum": 1},
         "scanDirs": {"type": "array", "items": {"type": "string"}},
         "output": {"type": "string"},