@bobfrankston/wallplater 1.0.5 → 1.0.6

package/README.md

@@ -1,15 +1,15 @@
 # @bobfrankston/wallplater
 
-JSON-driven wall-plate generator (Decora / duplex / blank gangs). Reads a small
-JSON config and emits a multi-object 3MF (plate + labels as separate,
-individually colourable objects) or per-part STLs.
+JSON-driven wall-plate generator (Decora / duplex / blank / button gangs). Reads
+a small JSON (JSON5) config and emits a multi-object 3MF (plate + labels as
+separate, individually colourable objects) or per-part STLs.
 
 ## Engines
 
 | Engine | Flag | Needs OpenSCAD? | Speed | Notes |
 |---|---|---|---|---|
 | **manifold** (default) | — | no | ~1 s | Direct geometry via [manifold-3d](https://github.com/elalish/manifold) (Clipper2 + robust CSG). Text via [opentype.js](https://github.com/opentypejs/opentype.js). |
-| **scad** (legacy) | `-scad` or `"engine":"scad"` | yes | ~30 s | Writes a `.scad` and shells out to OpenSCAD. Reference / fallback. Does **not** render rocker/header labels. |
+| **scad** (legacy) | `-scad` or `"engine":"scad"` | yes | ~30 s | Writes a `.scad` and shells out to OpenSCAD. Reference / fallback. Renders all hole geometry (incl. button pips) but **not** rocker/header/per-button labels. |
 
 The manifold engine has no system dependency beyond Node and is the path
 forward; `-scad` is kept for parity/verification.
@@ -56,8 +56,21 @@ directory), so a specific file carries only what differs — often just `name`,
 `gangs`, and a `breaker.switch`. Every default lives in `defaults.json`, not in
 code.
 
-Lengths are written **CSS-style with a unit suffix**: `"0.375in"`, `"5mm"`,
-`"-42mm"`. A bare number is treated as millimetres. Angles are plain numbers.
+Configs are parsed with **JSON5** (the most lenient reader), so comments
+(`//`, `/* */`), trailing commas, and unquoted keys are all allowed — plain JSON
+still works unchanged.
+
+Lengths are written **CSS-style with a unit suffix**. Supported units:
+
+| Suffix | Meaning | mm |
+|---|---|---|
+| `in` | inch | 25.4 |
+| `ft` | foot | 304.8 |
+| `cm` | centimetre | 10 |
+| `mm` | millimetre | 1 |
+
+e.g. `"0.375in"`, `"5mm"`, `"2cm"`, `"0.5ft"`, `"-42mm"`. A bare number (no
+suffix) is treated as millimetres. Angles (e.g. `cskAngle`) are plain numbers.
 
 ```jsonc
 // KitchenBack.json — only what differs from defaults.json
@@ -72,7 +85,7 @@ Lengths are written **CSS-style with a unit suffix**: `"0.375in"`, `"5mm"`,
 }
 ```
 
-- `gangs[].type`: `"decora"` | `"duplex"` | `"blank"`.
+- `gangs[].type`: `"decora"` | `"duplex"` | `"blank"` | `"button"`.
 - `gangs[].screws`: `false` to omit that gang's screw holes (default true).
 - `gangs[].legend`: single label centred above the gang's opening (positioned
   clear of the screw holes; `legendY` / `legendSize`).
@@ -112,6 +125,40 @@ overflow. See `../triple_demo.json` for a worked single-gang example.
 > Rocker/header labels are rendered by the **manifold engine only**. The
 > `-scad` engine ignores them (it warns).
 
+### Button gangs (round holes in a pip layout)
+
+A `"button"` gang punches a set of round button holes (default **0.5 in**
+diameter) arranged symmetrically like the pips on a die / playing card — odd
+counts put a single button in the centre. Set the count with `buttons` (1–9):
+
+```jsonc
+{
+  "type": "button",
+  "legend": "FAN",                       // the legend "on top" (above the buttons)
+  "buttons": 3,                          // 1-9; pip layout, single = centre
+  "buttonD": "0.5in",                    // optional per-gang diameter (default dims.buttonD)
+  "buttonLegends": ["HI", "MED", "LO"]   // optional small per-button labels
+}
+```
+
+- `buttons`: number of holes (1–9). Setting it implies `type:"button"`. The pip
+  pattern is the standard die/domino layout, read **top → bottom, left → right**:
+  `1`=centre, `2`/`3`=diagonal, `4`/`5`=corners (+centre for 5), `6`/`7`=two
+  columns (+centre for 7), `8`/`9`=full ring/grid. Counts above 9 are an error.
+- `buttonD`: per-gang hole diameter; defaults to `dims.buttonD` (`0.5in`).
+- `buttonLegends`: small labels, one per button in pip reading order (`""` or a
+  short array skips some). They are **in addition to** the gang `legend` on top,
+  and print in the accent colour. Sizing/placement: `buttonLegendSize` (3 mm),
+  `buttonLegendGap` (1 mm, below each hole).
+- Pip spacing is `dims.buttonPitch` (`0.85in` centre-to-centre). A button gang
+  mounts like a device — it gets a screw pair on the Decora line unless
+  `"screws": false`.
+
+See `../buttons_demo.json` for a worked Decora-plus-buttons example.
+
+> Per-button legends are rendered by the **manifold engine only** (the `-scad`
+> engine emits the button holes but skips the small labels, and warns).
+
 See `../decora_wallplate_spec.md` for the dimensional reference and print notes
 (print front-face-down; PETG/ASA recommended for heat near devices; keep plate
 and labels the same material family — see the chat note on ABS+PLA).

package/config.d.ts

@@ -1,9 +1,9 @@
 export declare const IN = 25.4;
-export type GangType = "blank" | "decora" | "duplex";
+export type GangType = "blank" | "decora" | "duplex" | "button";
 export type Engine = "manifold" | "scad";
-/** A length: CSS-style unit string ("0.375in" / "5mm") or a bare number (mm). */
+/** A length: CSS-style unit string ("0.375in" / "5mm" / "2cm" / "0.5ft") or a bare number (mm). */
 export type Len = string | number;
-/** Parse a length to millimetres. */
+/** Parse a length to millimetres. A bare number (no suffix) is millimetres. */
 export declare function mm(v: Len): number;
 export interface RockerCfg {
     left?: string;
@@ -13,6 +13,9 @@ export interface GangCfg {
     type?: GangType;
     opening?: boolean;
     legend?: string;
+    buttons?: number;
+    buttonD?: Len;
+    buttonLegends?: string[];
     filler?: boolean;
     screws?: boolean;
     rockers?: RockerCfg[];
@@ -38,6 +41,8 @@ export interface DimsCfg {
     duplexW?: Len;
     duplexH?: Len;
     duplexSpacing?: Len;
+    buttonD?: Len;
+    buttonPitch?: Len;
     screwSpacing?: Len;
     blankScrewSpacing?: Len;
     screwClearD?: Len;
@@ -56,6 +61,8 @@ export interface Config {
     rockerGap?: Len;
     headerSize?: Len;
     headerGap?: Len;
+    buttonLegendSize?: Len;
+    buttonLegendGap?: Len;
     bevel?: Len;
     labelDepth?: Len;
     blankScrews?: boolean;
@@ -90,6 +97,8 @@ export interface Dims {
     duplexW: number;
     duplexH: number;
     duplexSpacing: number;
+    buttonD: number;
+    buttonPitch: number;
     screwSpacing: number;
     blankScrewSpacing: number;
     screwClearD: number;
@@ -109,6 +118,8 @@ export interface Resolved {
     rockerGap: number;
     headerSize: number;
     headerGap: number;
+    buttonLegendSize: number;
+    buttonLegendGap: number;
     bevel: number;
     labelDepth: number;
     blankScrews: boolean;
@@ -124,4 +135,10 @@ export interface Resolved {
 }
 export declare function loadConfig(path: string): Resolved;
 export declare function gangType(g: GangCfg): GangType;
+/**
+ * Pip layout for a button gang: grid coordinates (gx, gy) each in {-1, 0, 1}
+ * (gy up), die/domino style, in reading order (top -> bottom, left -> right).
+ * Odd counts include the centre (0, 0). Supports 1-9.
+ */
+export declare function pipGrid(n: number): [number, number][];
 //# sourceMappingURL=config.d.ts.map

package/config.js

@@ -5,25 +5,29 @@
  * (in this directory), so a specific file need only carry what differs — often
  * just `name`, `gangs`, and a `breaker.switch`.
  *
- * Lengths are written CSS-style with a unit suffix: "0.375in", "5mm", "-42mm".
- * A bare number is treated as millimetres. Angles are plain numbers (degrees).
+ * Lengths are written CSS-style with a unit suffix: "0.375in", "5mm", "2cm",
+ * "0.5ft", "-42mm". A bare number is treated as millimetres. Angles are plain
+ * numbers (degrees).
  */
 import { readFileSync } from "fs";
 import { join } from "path";
+import JSON5 from "json5";
 export const IN = 25.4;
-/** Parse a length to millimetres. */
+/** Millimetres per supported length unit. */
+const UNIT = { mm: 1, cm: 10, in: IN, ft: 12 * IN };
+/** Parse a length to millimetres. A bare number (no suffix) is millimetres. */
 export function mm(v) {
     if (typeof v === "number")
         return v;
-    const m = /^\s*(-?[\d.]+)\s*(mm|in)?\s*$/i.exec(v);
+    const m = /^\s*(-?[\d.]+)\s*(mm|cm|in|ft)?\s*$/i.exec(v);
     if (!m)
-        throw new Error(`invalid length "${v}" (use e.g. "0.375in" or "5mm")`);
-    const n = parseFloat(m[1]);
-    return m[2] && m[2].toLowerCase() === "in" ? n * IN : n;
+        throw new Error(`invalid length "${v}" (use e.g. "0.375in", "5mm", "2cm", "0.5ft")`);
+    return parseFloat(m[1]) * UNIT[(m[2] ?? "mm").toLowerCase()];
 }
-// JSON.parse returns dynamic shape; merged then validated below.
+// JSON5 (lenient: comments, trailing commas, unquoted keys) returns dynamic
+// shape; merged then validated below.
 function readJson(path) {
-    return JSON.parse(readFileSync(path, "utf8"));
+    return JSON5.parse(readFileSync(path, "utf8"));
 }
 /** Deep-merge plain objects; arrays and scalars from `over` replace `base`. */
 function deepMerge(base, over) {
@@ -50,6 +54,7 @@ export function loadConfig(path) {
         faceT: mm(d.faceT), rimW: mm(d.rimW), cornerR: mm(d.cornerR),
         openW: mm(d.openW), openH: mm(d.openH), openR: mm(d.openR),
         duplexW: mm(d.duplexW), duplexH: mm(d.duplexH), duplexSpacing: mm(d.duplexSpacing),
+        buttonD: mm(d.buttonD), buttonPitch: mm(d.buttonPitch),
         screwSpacing: mm(d.screwSpacing), blankScrewSpacing: mm(d.blankScrewSpacing),
         screwClearD: mm(d.screwClearD), screwHeadD: mm(d.screwHeadD), cskAngle: d.cskAngle,
     };
@@ -62,6 +67,7 @@ export function loadConfig(path) {
         gangBreakerSize: mm(c.gangBreakerSize), gangBreakerY: mm(c.gangBreakerY),
         rockerSize: mm(c.rockerSize), rockerGap: mm(c.rockerGap),
         headerSize: mm(c.headerSize), headerGap: mm(c.headerGap),
+        buttonLegendSize: mm(c.buttonLegendSize), buttonLegendGap: mm(c.buttonLegendGap),
         bevel: mm(c.bevel), labelDepth: mm(c.labelDepth),
         blankScrews: c.blankScrews,
         font: c.font, fontFile: c.fontFile,
@@ -74,8 +80,32 @@ export function loadConfig(path) {
 export function gangType(g) {
     if (g.type)
         return g.type;
+    if (g.buttons && g.buttons > 0)
+        return "button"; // count implies a button gang
     if (g.opening === true)
         return "decora";
     return "blank";
 }
+/**
+ * Pip layout for a button gang: grid coordinates (gx, gy) each in {-1, 0, 1}
+ * (gy up), die/domino style, in reading order (top -> bottom, left -> right).
+ * Odd counts include the centre (0, 0). Supports 1-9.
+ */
+export function pipGrid(n) {
+    const grid = {
+        1: [[0, 0]],
+        2: [[-1, 1], [1, -1]],
+        3: [[-1, 1], [0, 0], [1, -1]],
+        4: [[-1, 1], [1, 1], [-1, -1], [1, -1]],
+        5: [[-1, 1], [1, 1], [0, 0], [-1, -1], [1, -1]],
+        6: [[-1, 1], [1, 1], [-1, 0], [1, 0], [-1, -1], [1, -1]],
+        7: [[-1, 1], [1, 1], [-1, 0], [0, 0], [1, 0], [-1, -1], [1, -1]],
+        8: [[-1, 1], [0, 1], [1, 1], [-1, 0], [1, 0], [-1, -1], [0, -1], [1, -1]],
+        9: [[-1, 1], [0, 1], [1, 1], [-1, 0], [0, 0], [1, 0], [-1, -1], [0, -1], [1, -1]],
+    };
+    const p = grid[n];
+    if (!p)
+        throw new Error(`buttons: count ${n} unsupported (pip layout is 1-9)`);
+    return p;
+}
 //# sourceMappingURL=config.js.map

package/defaults.json

@@ -9,6 +9,8 @@
   "rockerGap": "1.5mm",
   "headerSize": "4mm",
   "headerGap": "5mm",
+  "buttonLegendSize": "3mm",
+  "buttonLegendGap": "1mm",
   "bevel": "1.2mm",
   "labelDepth": "0.6mm",
   "blankScrews": true,
@@ -34,6 +36,8 @@
     "duplexW": "1.34375in",
     "duplexH": "1.125in",
     "duplexSpacing": "1.5in",
+    "buttonD": "0.5in",
+    "buttonPitch": "0.85in",
     "screwSpacing": "3.8125in",
     "blankScrewSpacing": "3.281in",
     "screwClearD": "4mm",

package/geometry.js

@@ -6,7 +6,7 @@
  * print-oriented, ready for build3mf() or writeBinaryStl().
  */
 import Module from "manifold-3d";
-import { gangType } from "./config.js";
+import { gangType, pipGrid, mm } from "./config.js";
 import { loadFont, textToContours } from "./text.js";
 const SEG = 96; // circular segments (matches the SCAD $fn = 96)
 let wasm = null;
@@ -83,6 +83,14 @@ export async function buildMeshes(cfg) {
             if (sc)
                 cutters.push(screw(x, 0)); // single centre screw
         }
+        else if (t === "button") { // round button holes in a pip layout
+            const bd = g.buttonD !== undefined ? mm(g.buttonD) : d.buttonD;
+            for (const [gx, gy] of pipGrid(g.buttons))
+                cutters.push(Manifold.cylinder(DEPTH + 2, bd / 2, bd / 2, SEG)
+                    .translate([x + gx * d.buttonPitch, gy * d.buttonPitch, -1]));
+            if (sc)
+                screwsPair(x, d.screwSpacing); // mounts like a device, on the Decora line
+        }
         else if (cfg.blankScrews && sc) { // blank: box-ear line, or Decora line if a filler plate
             screwsPair(x, g.filler ? d.screwSpacing : d.blankScrewSpacing);
         }
@@ -101,6 +109,18 @@ export async function buildMeshes(cfg) {
             accent.push({ txt: g.breaker, size: cfg.gangBreakerSize, halign: "right", x: gx + openHalf, y: cfg.gangBreakerY });
         if ((g.header ?? "") !== "")
             accent.push({ txt: g.header, size: cfg.headerSize, halign: "center", x: gx, y: openTop + cfg.headerGap });
+        if (gangType(g) === "button") { // per-button legends, small, below each hole
+            const bd = g.buttonD !== undefined ? mm(g.buttonD) : d.buttonD;
+            const bl = g.buttonLegends ?? [];
+            const pips = pipGrid(g.buttons);
+            for (let j = 0; j < pips.length; j++) {
+                if ((bl[j] ?? "") === "")
+                    continue;
+                const [px, py] = pips[j];
+                accent.push({ txt: bl[j], size: cfg.buttonLegendSize, halign: "center",
+                    x: gx + px * d.buttonPitch, y: py * d.buttonPitch - bd / 2 - cfg.buttonLegendGap });
+            }
+        }
         const rk = g.rockers ?? [];
         for (let j = 0; j < rk.length; j++) {
             const yr = openTop - (j + 0.5) * (d.openH / rk.length); // rockers top -> bottom

package/index.js

@@ -35,8 +35,8 @@ function partList(cfg) {
     return parts;
 }
 function runScadEngine(cfg, dir) {
-    if (cfg.gangs.some((g) => (g.rockers?.length ?? 0) > 0 || (g.header ?? "") !== "" || (g.breaker ?? "") !== ""))
-        console.warn("  ! per-gang rocker/header/breaker labels are only rendered by the manifold engine; the -scad engine ignores them.");
+    if (cfg.gangs.some((g) => (g.rockers?.length ?? 0) > 0 || (g.header ?? "") !== "" || (g.breaker ?? "") !== "" || (g.buttonLegends?.length ?? 0) > 0))
+        console.warn("  ! per-gang rocker/header/breaker labels and per-button legends are only rendered by the manifold engine; the -scad engine ignores them (button holes themselves are emitted).");
     const scadPath = join(dir, `${cfg.name}.scad`);
     writeFileSync(scadPath, generateScad(cfg));
     console.log("wrote", basename(scadPath));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/wallplater",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "type": "module",
   "description": "JSON-driven wall-plate generator (Decora / duplex / blank). Direct-to-3MF via manifold-3d, with an optional OpenSCAD engine.",
   "main": "index.js",
@@ -19,6 +19,7 @@
     "release": "npmglobalize"
   },
   "dependencies": {
+    "json5": "^2.2.3",
     "manifold-3d": "^3.0.0",
     "opentype.js": "^1.3.4"
   },

package/scad.js

@@ -17,11 +17,13 @@ export function generateScad(cfg) {
     const legend = "[" + cfg.gangs.map((g) => `"${g.legend ?? ""}"`).join(", ") + "]";
     const filler = "[" + cfg.gangs.map((g) => (g.filler ? "true" : "false")).join(", ") + "]";
     const screws = "[" + cfg.gangs.map((g) => (g.screws === false ? "false" : "true")).join(", ") + "]";
+    const buttons = "[" + cfg.gangs.map((g) => num(g.buttons ?? 0)).join(", ") + "]";
     const params = `// ===== Auto-generated by wallplater from ${cfg.name}.json — do not hand-edit =====
 GANGS         = ${gangs};   // per gang: "blank" | "decora" | "duplex"
 LEGEND        = ${legend};
 FILLER        = ${filler};   // blank gang has a filler/insert plate -> screws on Decora line
 SCREWS        = ${screws};   // per gang: place screw holes? (false = omit)
+BUTTONS       = ${buttons};   // per gang: button-hole count (0 = not a button gang)
 GANG_PITCH    = ${num(d.gangPitch)};
 ONE_GANG_W    = ${num(d.oneGangWidth)};
 PLATE_H       = ${num(d.height)};
@@ -36,6 +38,8 @@ OPEN_R        = ${num(d.openR)};
 DUPLEX_W      = ${num(d.duplexW)};
 DUPLEX_H      = ${num(d.duplexH)};
 DUPLEX_SPACING= ${num(d.duplexSpacing)};
+BUTTON_D      = ${num(d.buttonD)};
+BUTTON_PITCH  = ${num(d.buttonPitch)};
 SCREW_SPACING = ${num(d.screwSpacing)};
 BLANK_SCREW_SPACING = ${num(d.blankScrewSpacing)};
 BLANK_SCREWS  = ${cfg.blankScrews};
@@ -82,6 +86,24 @@ module duplex_opening(x)
         translate([x, s * DUPLEX_SPACING/2, -1]) linear_extrude(DEPTH + 2)
             intersection() { circle(d = DUPLEX_W); square([DUPLEX_W, DUPLEX_H], center = true); }
 
+// pip grid: [gx, gy] in {-1,0,1} (gy up), die/domino style, centre for odd counts (1-9)
+function pip_grid(n) =
+    n == 1 ? [[0,0]] :
+    n == 2 ? [[-1,1],[1,-1]] :
+    n == 3 ? [[-1,1],[0,0],[1,-1]] :
+    n == 4 ? [[-1,1],[1,1],[-1,-1],[1,-1]] :
+    n == 5 ? [[-1,1],[1,1],[0,0],[-1,-1],[1,-1]] :
+    n == 6 ? [[-1,1],[1,1],[-1,0],[1,0],[-1,-1],[1,-1]] :
+    n == 7 ? [[-1,1],[1,1],[-1,0],[0,0],[1,0],[-1,-1],[1,-1]] :
+    n == 8 ? [[-1,1],[0,1],[1,1],[-1,0],[1,0],[-1,-1],[0,-1],[1,-1]] :
+    n == 9 ? [[-1,1],[0,1],[1,1],[-1,0],[0,0],[1,0],[-1,-1],[0,-1],[1,-1]] :
+    [];
+
+module button_holes(x, n)
+    for (p = pip_grid(n))
+        translate([x + p[0]*BUTTON_PITCH, p[1]*BUTTON_PITCH, -1])
+            cylinder(d = BUTTON_D, h = DEPTH + 2);
+
 module outline() rrect(PLATE_W, PLATE_H, CORNER_R);
 
 module plate_body() {
@@ -120,6 +142,7 @@ module plate() {
             sc = (i >= len(SCREWS)) || SCREWS[i];                         // place screws on this gang?
             if (t == "decora")      { decora_opening(x); if (sc) screws_pair(x, SCREW_SPACING); }
             else if (t == "duplex") { duplex_opening(x); if (sc) screw(x, 0); }   // single centre screw
+            else if (t == "button") { button_holes(x, BUTTONS[i]); if (sc) screws_pair(x, SCREW_SPACING); }
             else if (BLANK_SCREWS && sc)                                  // blank: box-ear line, or Decora line if a filler plate
                 screws_pair(x, (i < len(FILLER) && FILLER[i]) ? SCREW_SPACING : BLANK_SCREW_SPACING);
         }