From 58d241a2a35ea52fc340d676ed36f1cc6018019f Mon Sep 17 00:00:00 2001 From: Ho Ngoc Hai Date: Thu, 5 Feb 2026 23:45:15 +0700 Subject: [PATCH] docs: Add new section on 'Wrap Property Not Working Reliably' to PITFALLS.md, detailing issues and solutions for layout management in Pencil design. --- .../pencil-design/references/PITFALLS.md | 71 +++++++++++++++++++ .../landing/desktop.pen} | 0 .../landing/mobile.pen} | 0 .../landing/tablet.pen} | 0 .../{tPOS-main-cafe.pen => tPOS/pos/cafe.pen} | 0 .../pos/karaoke.pen} | 0 .../pos/restaurant.pen} | 0 .../{tPOS-main-spa.pen => tPOS/pos/spa.pen} | 0 8 files changed, 71 insertions(+) rename pencil-design/src/pages/{tPOS-desktop-home.pen => tPOS/landing/desktop.pen} (100%) rename pencil-design/src/pages/{tPOS-mobile-home.pen => tPOS/landing/mobile.pen} (100%) rename pencil-design/src/pages/{tPOS-tablet-home.pen => tPOS/landing/tablet.pen} (100%) rename pencil-design/src/pages/{tPOS-main-cafe.pen => tPOS/pos/cafe.pen} (100%) rename pencil-design/src/pages/{tPOS-main-karaoke.pen => tPOS/pos/karaoke.pen} (100%) rename pencil-design/src/pages/{tPOS-main-restaurant.pen => tPOS/pos/restaurant.pen} (100%) rename pencil-design/src/pages/{tPOS-main-spa.pen => tPOS/pos/spa.pen} (100%) diff --git a/.agent/skills/pencil-design/references/PITFALLS.md b/.agent/skills/pencil-design/references/PITFALLS.md index d7a17d70..cf612419 100644 --- a/.agent/skills/pencil-design/references/PITFALLS.md +++ b/.agent/skills/pencil-design/references/PITFALLS.md @@ -15,6 +15,7 @@ Comprehensive list of common mistakes when working with Pencil `.pen` files and 9. [Using Emoji Text for Icons](#9-using-emoji-text-for-icons) 10. [Build Script Not Scanning Subdirectories](#10-build-script-not-scanning-subdirectories) 11. [Components at Root Level](#11-components-at-root-level) +12. [Wrap Property Not Working Reliably](#12-wrap-property-not-working-reliably) --- @@ -301,6 +302,75 @@ for pen_file in sorted(dir_path.rglob('*.pen')): --- +## 12. Wrap Property Not Working Reliably + +**Problem**: Setting `wrap: true` on a frame expects children to wrap to next row when exceeding container width. However, Pencil's wrap behavior is unreliable and often causes overflow instead of wrapping. + +**Symptom**: Elements overflow beyond container boundary instead of wrapping. + +**Solution**: Use manual rows with explicit horizontal layout instead of relying on wrap. + +```json +// ❌ BAD: wrap không hoạt động như mong đợi +{ + "type": "frame", + "id": "TableGrid", + "width": "fill_container", + "layout": "horizontal", + "wrap": true, + "gap": 8, + "children": [ + {"type": "frame", "id": "Table1", "width": 72, "height": 72}, + {"type": "frame", "id": "Table2", "width": 72, "height": 72}, + {"type": "frame", "id": "Table3", "width": 72, "height": 72}, + {"type": "frame", "id": "Table4", "width": 72, "height": 72}, + {"type": "frame", "id": "Table5", "width": 72, "height": 72}, + {"type": "frame", "id": "Table6", "width": 72, "height": 72} + ] +} + +// ✅ GOOD: Manual rows - chắc chắn layout đúng +{ + "type": "frame", + "id": "TableGrid", + "width": "fill_container", + "layout": "vertical", + "gap": 8, + "clip": true, + "children": [ + { + "type": "frame", + "id": "Row1", + "width": "fill_container", + "gap": 8, + "children": [ + {"type": "frame", "id": "Table1", "width": 72, "height": 72}, + {"type": "frame", "id": "Table2", "width": 72, "height": 72}, + {"type": "frame", "id": "Table3", "width": 72, "height": 72} + ] + }, + { + "type": "frame", + "id": "Row2", + "width": "fill_container", + "gap": 8, + "children": [ + {"type": "frame", "id": "Table4", "width": 72, "height": 72}, + {"type": "frame", "id": "Table5", "width": 72, "height": 72}, + {"type": "frame", "id": "Table6", "width": 72, "height": 72} + ] + } + ] +} +``` + +**Tip**: Khi cần grid layout trong container có chiều rộng cố định: +- Dùng `layout: vertical` cho container chính +- Tạo các row con với `layout: horizontal` (mặc định) +- Thêm `clip: true` để tránh overflow + +--- + ## Quick Checklist / Checklist Nhanh Before committing `.pen` files: @@ -311,5 +381,6 @@ Before committing `.pen` files: - [ ] Icons use `icon_font` not emoji text - [ ] Build script uses `rglob()` for subdirectories - [ ] Components wrapped in layout frames, not at root level +- [ ] **Avoid `wrap: true` - use manual rows instead** - [ ] Run `jq empty file.pen` to validate JSON syntax - [ ] Run `python3 scripts/build.py --library` before testing diff --git a/pencil-design/src/pages/tPOS-desktop-home.pen b/pencil-design/src/pages/tPOS/landing/desktop.pen similarity index 100% rename from pencil-design/src/pages/tPOS-desktop-home.pen rename to pencil-design/src/pages/tPOS/landing/desktop.pen diff --git a/pencil-design/src/pages/tPOS-mobile-home.pen b/pencil-design/src/pages/tPOS/landing/mobile.pen similarity index 100% rename from pencil-design/src/pages/tPOS-mobile-home.pen rename to pencil-design/src/pages/tPOS/landing/mobile.pen diff --git a/pencil-design/src/pages/tPOS-tablet-home.pen b/pencil-design/src/pages/tPOS/landing/tablet.pen similarity index 100% rename from pencil-design/src/pages/tPOS-tablet-home.pen rename to pencil-design/src/pages/tPOS/landing/tablet.pen diff --git a/pencil-design/src/pages/tPOS-main-cafe.pen b/pencil-design/src/pages/tPOS/pos/cafe.pen similarity index 100% rename from pencil-design/src/pages/tPOS-main-cafe.pen rename to pencil-design/src/pages/tPOS/pos/cafe.pen diff --git a/pencil-design/src/pages/tPOS-main-karaoke.pen b/pencil-design/src/pages/tPOS/pos/karaoke.pen similarity index 100% rename from pencil-design/src/pages/tPOS-main-karaoke.pen rename to pencil-design/src/pages/tPOS/pos/karaoke.pen diff --git a/pencil-design/src/pages/tPOS-main-restaurant.pen b/pencil-design/src/pages/tPOS/pos/restaurant.pen similarity index 100% rename from pencil-design/src/pages/tPOS-main-restaurant.pen rename to pencil-design/src/pages/tPOS/pos/restaurant.pen diff --git a/pencil-design/src/pages/tPOS-main-spa.pen b/pencil-design/src/pages/tPOS/pos/spa.pen similarity index 100% rename from pencil-design/src/pages/tPOS-main-spa.pen rename to pencil-design/src/pages/tPOS/pos/spa.pen