create-shopify-scss-autofill 0.6.1 → 0.6.3

package/package.json

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

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

@@ -1,6 +1,6 @@
 # scss-kit 维护备忘（持续迭代）
 
-更新时间：2026-03-19
+更新时间：2026-03-31
 
 这份文档的目的：把 scss-kit 的“关键约束 / 设计决策 / 发布要点”固化下来，方便我们后续持续更新、迭代而不走回头路。
 
@@ -43,12 +43,14 @@
   - 默认 safe mode：Sass 输出到 `src/.sass-out/` → 安全同步到 `assets/`
 
 - `npm run dev:theme:auto`
-  - 并行：responsive:watch + css:watch + theme:watch
+  - 启动前先运行 `scss-kit:generate` + `scss-kit:responsive:generate` + `scss-kit:responsive:generate:entries`
+  - 然后并行：responsive:watch + css:watch + theme:watch
 
 ## 扫描器策略（稳定性）
 
 - 优先 AST（`postcss` + `postcss-scss`），失败回退 legacy 正则扫描。
-- AST 依赖是“可选按需加载”，保证“先 init 再 install”的接入流程可用。
+- AST 依赖是"可选按需加载"，保证"先 init 再 install"的接入流程可用。
+- `responsive:generate` 扫描时会排除所有 `_responsive-autofill*.generated.scss` 文件，防止循环扫描。
 
 ## 发布/脚手架（npm create）
 
@@ -65,6 +67,7 @@
 ## 扩展能力
 
 - **r.re() 短写映射**：`RE_SHORTHAND_MAP` 存放快捷写法（如 `grid-cols-N`、`span-N`），PC 侧由 SCSS `$_re-shorthands` map + `_expand-re()` 展开，Mobile 侧由 JS `expandReValue()` 展开。
+- **varScope**：`autofill.entries` 支持 `{ file, varScope }` 对象格式，把 CSS 变量作用域限定到指定选择器。
 - **VS Code 代码片段**：`.vscode/scss-kit.code-snippets` 提供函数签名补全。
 - **增量缓存**：`.scss-kit-cache.json`（已加入 `.gitignore`）存储源文件哈希与配置哈希。
 

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

@@ -57,6 +57,23 @@
 - 顶部 `@use "./_responsive-autofill.<page>.generated" as auto;`
 - 底部 `@include auto.responsive_autofill_overrides();`（确保覆盖顺序）
 
+### varScope（可选）
+
+默认情况下，`--px-to-vw` 和 `--px-to-vw-mb` 变量声明在 `:root` 上。如果页面需要将变量作用域限定到特定选择器（例如 section 级别），可以在 `autofill.entries` 中使用对象格式：
+
+```json
+{
+  "autofill": {
+    "entries": [
+      "src/styles/page-a.scss",
+      { "file": "src/styles/page-b.scss", "varScope": ".page-b-wrapper" }
+    ]
+  }
+}
+```
+
+`page-b` 生成的 CSS 变量将挂载在 `.page-b-wrapper` 而非 `:root`。
+
 推荐约定：
 
 - 字体/需要下限兜底的值：使用 `r.resp(pc, mobile, desktopType[, mobileType])`

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

@@ -174,7 +174,7 @@ function loadConfig() {
 }
 
 function toPosix(p) {
-  return p.replaceAll('\\\\', '/')
+  return p.replaceAll('\\', '/')
 }
 
 function ensurePx(v) {
@@ -519,11 +519,10 @@ function generateReShorthandMap() {
   }
   // opacity shortcuts (0, 10, 20, ..., 100)
   for (let o = 0; o <= 100; o += 10) {
-    entries.push(`  opacity-${o}: ${o / 100}`)
+    entries.push(`  opacity-${o}: ${o === 0 ? 0 : o / 100}`)
   }
   entries.push(`  opacity-5: 0.05`)
   entries.push(`  opacity-25: 0.25`)
-  entries.push(`  opacity-50: 0.5`)
   entries.push(`  opacity-75: 0.75`)
   return '\n' + entries.join(',\n') + ',\n'
 }
@@ -746,13 +745,22 @@ function getAutofillEntries(cfg) {
   if (!Array.isArray(entries)) {
     throw new Error('autofill.entries must be an array of entry scss paths')
   }
-  return entries.filter(Boolean)
+  // Each entry may be a string path or an object { file, varScope }
+  return entries.filter(Boolean).map((e) => {
+    if (typeof e === 'string') return { file: e, varScope: null }
+    if (e && typeof e === 'object' && typeof e.file === 'string')
+      return { file: e.file, varScope: e.varScope ?? null }
+    throw new Error(
+      'autofill.entries items must be a string path or { file, varScope }'
+    )
+  })
 }
 
-function generateAutofillScss(cfg, collectedRules) {
+function generateAutofillScss(cfg, collectedRules, varScope) {
   const { ns, mobileMax } = getAutofill(cfg)
   const desktopWidth = cfg?.design?.desktopWidth ?? 1920
   const mobileWidth = cfg?.design?.mobileWidth ?? 750
+  const scope = varScope ?? ':root'
 
   const header = `@use "./responsive" as ${ns};
 
@@ -764,12 +772,27 @@ function generateAutofillScss(cfg, collectedRules) {
   const mixinHeader = `@mixin responsive_autofill_overrides() {\n`
   const mixinFooter = `\n}\n`
 
+  // PC vars block: 2-space indent inside mixin, 4-space for property
+  const pcVarsBlock =
+    `  ${scope} {\n` +
+    `    --px-to-vw: calc(100vw / ${desktopWidth});\n` +
+    `  }\n`
+
+  // MB vars block: 4-space indent inside @media, 6-space for property
+  const mbVarsBlock =
+    `    ${scope} {\n` +
+    `      --px-to-vw-mb: calc(100vw / ${mobileWidth});\n` +
+    `    }\n`
+
   if (!collectedRules.length) {
     return (
       header +
       mixinHeader +
-      `  :root {\n    --px-to-vw: calc(100vw / ${desktopWidth});\n  }\n\n` +
-      `  @media screen and (max-width: ${mobileMax}px) {\n    :root {\n      --px-to-vw-mb: calc(100vw / ${mobileWidth});\n    }\n  }\n` +
+      pcVarsBlock +
+      `\n` +
+      `  @media screen and (max-width: ${mobileMax}px) {\n` +
+      mbVarsBlock +
+      `  }\n` +
       mixinFooter
     )
   }
@@ -793,9 +816,11 @@ function generateAutofillScss(cfg, collectedRules) {
   return (
     header +
     mixinHeader +
-    `  :root {\n    --px-to-vw: calc(100vw / ${desktopWidth});\n  }\n\n` +
+    pcVarsBlock +
+    `\n` +
     `  @media screen and (max-width: ${mobileMax}px) {\n` +
-    `    :root {\n      --px-to-vw-mb: calc(100vw / ${mobileWidth});\n    }\n\n` +
+    mbVarsBlock +
+    `\n` +
     blocks.map((b) => b.replaceAll(/^/gm, '    ')).join('\n\n') +
     `\n  }` +
     mixinFooter
@@ -883,7 +908,7 @@ function toScssMap(obj) {
   const entries = Object.entries(obj)
     .map(([k, v]) => `  ${k}: ${v},`)
     .join('\n')
-  return `(${entries}\n)`
+  return `(\n${entries}\n)`
 }
 
 function generateResponsiveScss(cfg) {
@@ -1184,7 +1209,7 @@ function patchPackageJson(cfg) {
     'dev:theme':
       'concurrently -k -n CSS,THEME "npm:css:watch" "npm:theme:watch"',
     'dev:theme:auto':
-      'npm run scss-kit:generate && npm run scss-kit:responsive:generate && concurrently -k -n AUTO,CSS,THEME "npm:responsive:watch" "npm:css:watch" "npm:theme:watch"',
+      'npm run scss-kit:generate && npm run scss-kit:responsive:generate && npm run scss-kit:responsive:generate:entries && concurrently -k -n AUTO,CSS,THEME "npm:responsive:watch" "npm:css:watch" "npm:theme:watch"',
   }
   for (const [k, v] of Object.entries(watchScripts)) {
     if (pkg.scripts[k] && pkg.scripts[k] !== v) conflicts.push(`scripts.${k}`)
@@ -1491,7 +1516,15 @@ function main() {
       const backupPath = backupFile(outAbs)
       try {
         const collected = scanScssForAutofill(targetAbs, autofill)
-        const scss = generateAutofillScss(config, collected)
+        // Look up varScope for this entry from config
+        const entryVarScope =
+          getAutofillEntries(config).find(
+            (e) =>
+              path.resolve(
+                path.isAbsolute(e.file) ? e.file : path.join(ROOT, e.file)
+              ) === path.resolve(targetAbs)
+          )?.varScope ?? null
+        const scss = generateAutofillScss(config, collected, entryVarScope)
         const res = writeFileSafely(outAbs, scss, {
           overwriteIfContains: 'Generated by scss-kit',
         })
@@ -1536,11 +1569,20 @@ function main() {
       walkScssFiles(path.isAbsolute(d) ? d : path.join(ROOT, d), absFiles)
     }
 
-    // Avoid scanning the output file itself.
+    // Avoid scanning the output file itself and any per-entry generated files.
     const outputAbs = autofill.outputAbs
-    const files = absFiles.filter(
-      (f) => path.resolve(f) !== path.resolve(outputAbs)
-    )
+    const files = absFiles.filter((f) => {
+      const resolved = path.resolve(f)
+      if (resolved === path.resolve(outputAbs)) return false
+      // Skip all _responsive-autofill*.generated.scss files
+      const base = path.basename(f)
+      if (
+        base.startsWith('_responsive-autofill') &&
+        base.endsWith('.generated.scss')
+      )
+        return false
+      return true
+    })
 
     const collected = []
     for (const f of files) {
@@ -1579,15 +1621,16 @@ function main() {
         JSON.stringify(
           {
             action: 'responsive:generate:entries',
-            ok: false,
+            ok: true,
+            skipped: true,
             reason:
-              'missing autofill.entries in scss-kit.config.json (expected array of entry scss paths)',
+              'autofill.entries is empty — nothing to generate. Create .scss files in src/styles/ and the responsive:watch watcher will register them automatically.',
           },
           null,
           2
         )
       )
-      process.exit(1)
+      process.exit(0)
     }
 
     // Load incremental cache
@@ -1596,7 +1639,7 @@ function main() {
     const nextCache = { _configHash: configHash }
 
     const results = []
-    for (const entryRel of entries) {
+    for (const { file: entryRel, varScope: entryVarScope } of entries) {
       const entryAbs = path.isAbsolute(entryRel)
         ? entryRel
         : path.join(ROOT, entryRel)
@@ -1638,7 +1681,7 @@ function main() {
 
       try {
         const collected = scanScssForAutofill(entryAbs, autofill)
-        const scss = generateAutofillScss(config, collected)
+        const scss = generateAutofillScss(config, collected, entryVarScope)
         const res = writeFileSafely(outAbs, scss, {
           overwriteIfContains: 'Generated by scss-kit',
         })

package/template/tools/scss-kit/css-watch-safe.mjs

@@ -145,12 +145,12 @@ function removeCommentOnlyBlocks(cssText) {
 function hoistCssVars(cssText) {
   const lines = cssText.split(/\r?\n/)
 
-  const pcVarLines = []     // lines of :root { --px-to-vw }
-  let mbMediaHeader = ''    // @media header for the --px-to-vw-mb block
-  const mbVarLines = []     // lines of :root { --px-to-vw-mb }
+  const pcVarLines = [] // lines of :root { --px-to-vw }
+  let mbMediaHeader = '' // @media header for the --px-to-vw-mb block
+  const mbVarLines = [] // lines of :root { --px-to-vw-mb }
 
   const output = []
-  let markerPos = -1        // index in output where the marker line sits
+  let markerPos = -1 // index in output where the marker line sits
 
   let i = 0
   while (i < lines.length) {
@@ -170,7 +170,10 @@ function hoistCssVars(cssText) {
       const block = collectBlock(lines, i)
       i += block.length
       const blockText = block.join('\n')
-      if (blockText.includes('--px-to-vw:') && !blockText.includes('--px-to-vw-mb')) {
+      if (
+        blockText.includes('--px-to-vw:') &&
+        !blockText.includes('--px-to-vw-mb')
+      ) {
         pcVarLines.push(...block)
       } else {
         output.push(...block)
@@ -241,6 +244,8 @@ function hoistCssVars(cssText) {
 
   return output.join('\n').replace(/\n{3,}/g, '\n\n')
 }
+
+function syncOne(tmpCssAbs) {
   const relFromOut = path.relative(OUT_DIR, tmpCssAbs)
   const targetAbs = path.join(ASSETS_DIR, relFromOut)
   const targetRel = toPosix(path.relative(ROOT, targetAbs))
@@ -302,16 +307,18 @@ function hoistCssVars(cssText) {
 function startSassWatch() {
   ensureDir(OUT_DIR)
   const sassArgs = [
+    'sass',
     '--watch',
     `${toPosix(path.relative(ROOT, STYLES_DIR))}:${toPosix(
       path.relative(ROOT, OUT_DIR)
     )}`,
     '--style=expanded',
     '--no-source-map',
+    '--silence-deprecation=if-function',
   ]
 
   console.log('[scss-kit] starting sass watch (safe mode)')
-  const child = spawn('sass', sassArgs, {
+  const child = spawn('npx', sassArgs, {
     stdio: 'inherit',
     shell: process.platform === 'win32',
     cwd: ROOT,

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

@@ -45,7 +45,7 @@
         "mobileMax": {"type": "integer", "minimum": 1},
         "scanDirs": {"type": "array", "items": {"type": "string"}},
         "output": {"type": "string"},
-        "entries": {"type": "array", "items": {"type": "string"}}
+        "entries": {"type": "array", "items": {"oneOf": [{"type": "string"}, {"type": "object", "required": ["file"], "properties": {"file": {"type": "string"}, "varScope": {"type": "string"}}}]}}
       }
     },
     "themeKit": {