partforge 0.117.1 → 0.118.0

package/docs/AUTHORING-PARTS.md

@@ -1060,12 +1060,41 @@ export function tilePicker(host) {
    listener you attach yourself with `addEventListener`, rather than through `host.h`,
    is **not** guarded — wire listeners through `host.h`, or wrap your own in try/catch.
 
-**Looking native.** The slot inherits the rail's font, colours and light/dark theme.
-Bare `<button>`, `<input>` and `<select>` elements pick up the built-in looks
-automatically; the built-in classes are available by name for the exact thing:
+**Looking native.** The slot inherits the rail's font and text colour, and the
+built-in looks come for free: bare `<button>`, `<input>` and `<select>` elements
+are already styled, the built-in classes are there by name for the exact thing —
 `row`, `seg` (a segmented row of buttons), `action`, `ghost`, `num`, `text-input`,
-`select-input`; and for SVG, `pf-hit` (clickable, with a `selected` state) and
-`pf-drag`. Sub-controls mounted through `host.controls` *are* the built-in widgets.
+`select-input` — and sub-controls mounted through `host.controls` *are* the
+built-in widgets. For SVG there are two classes: `pf-hit` (a clickable region,
+with a `selected` state) and `pf-drag`.
+
+**Colour only with the rail's tokens.** Inheriting the rail's colours covers the
+text you did not style; it does not cover anything you colour yourself. For that,
+use a `--pf-*` custom property and never a hex literal or a named colour — the
+tokens flip with the light/dark theme and a literal cannot, so a `#333` border is
+a widget that is unreadable in one of the two themes. The ones worth knowing:
+`var(--pf-text)` and `var(--pf-text-2)` for text, `var(--pf-muted)` for a
+secondary label, `var(--pf-border)` for a rule or an outline,
+`var(--pf-surface-2)` for a filled chip, `var(--pf-accent)` with
+`var(--pf-on-accent)` for the selected or primary thing, and `var(--pf-err)` for
+a problem. That palette is the whole palette: the accent blue for the one thing
+that is chosen or primary, the surface and border greys for everything else. A
+widget that reaches past it for a red or a green is a widget that has stopped
+looking like the rest of the panel.
+
+**Nest a region's label inside the region.** The common case then needs no colour
+from you at all: an SVG shape you leave unfilled inherits `var(--pf-text-2)`
+rather than SVG's own black, a `pf-hit` region is filled and outlined at rest,
+and a `<text>` *inside* that region stays readable through all three states —
+the rail gives it `var(--pf-text-2)` at rest and `var(--pf-on-accent)` once the
+region is selected and has gone solid accent underneath it, and clears the
+stroke it would otherwise inherit from the region's outline (SVG paints that
+around every glyph, which at label sizes leaves a pale ghost of the number).
+Draw the label as a sibling instead and none of that reaches it: a dark number
+sitting on the selected blue is the result, and you have to colour it yourself.
+To colour a
+region from your own data, set an inline `style` — a `fill="…"` attribute loses
+to the rail's rule.
 
 **Reading the part's own files.** Artwork can live beside the code (the tree is text,
 so an SVG, a `partforge-vector` JSON document or a JSON data file — not a PNG).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.117.1",
+  "version": "0.118.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",

package/src/framework/app.css

@@ -387,10 +387,10 @@ button.action:disabled { opacity: .5; cursor: default; }
 /* Custom controls (type: "custom"): a part-authored widget in the rail. The
    slot inherits the rail's cascade (font, colours, --pf-* tokens); these rules
    give BARE elements the built-in controls' look so a widget written with
-   plain <button>/<input>/<select> still reads as native, and provide two
-   opt-in classes for SVG: .pf-hit (a clickable region) and .pf-drag (a
-   dragged one — touch-action: none is what lets a finger drag it on a phone
-   instead of scrolling the sheet). */
+   plain <button>/<input>/<select> still reads as native, supply a themed
+   floor for hand-drawn SVG, and provide two opt-in classes for SVG: .pf-hit
+   (a clickable region) and .pf-drag (a dragged one — touch-action: none is
+   what lets a finger drag it on a phone instead of scrolling the sheet). */
 .pf-custom { margin: 9px 0; }
 .pf-custom.hidden { display: none; }
 .pf-custom-slot { display: flow-root; }
@@ -400,7 +400,12 @@ button.action:disabled { opacity: .5; cursor: default; }
    like .text-input (0,1,0) or .row .num (0,2,0). At true zero specificity,
    any class rule wins, so a named built-in class (.seg button, .text-input,
    select.select-input, …) always beats these bare-element defaults. */
-:where(.pf-custom) :where(svg) { display: block; max-width: 100%; height: auto; }
+/* `fill` inherits in SVG, so this is the floor for everything the widget draws
+   and did not colour — including <text>. SVG's own initial fill is BLACK, which
+   is invisible on the dark theme, and that is what an author gets for free
+   unless the rail supplies a token. Inherited rather than matched, so a child
+   carrying its own fill="…" attribute still wins. */
+:where(.pf-custom) :where(svg) { display: block; max-width: 100%; height: auto; fill: var(--pf-text-2); }
 :where(.pf-custom) :where(button) {
   font: inherit; font-size: 12px; padding: 5px 9px; cursor: pointer;
   background: transparent; border: 1px solid var(--pf-border); color: var(--pf-text-2);
@@ -417,9 +422,29 @@ button.action:disabled { opacity: .5; cursor: default; }
   outline: none; border-color: var(--pf-accent);
   box-shadow: 0 0 0 3px color-mix(in oklab, var(--pf-accent) 35%, transparent);
 }
-.pf-custom .pf-hit { cursor: pointer; }
+/* A region the reader clicks. The RESTING fill and stroke are what make it read
+   as a control: without them a .pf-hit polygon is a black slab with no border
+   until it is hovered or selected. Zero specificity, so a widget that colours
+   regions from its own data still wins — with an inline `style`, since a
+   `fill="…"` attribute loses to any rule that matches the element, even this
+   one. Hover and selected below keep their own (0,2,x) weight. */
+:where(.pf-custom) :where(.pf-hit) { cursor: pointer; fill: var(--pf-surface-2); stroke: var(--pf-border); }
 .pf-custom .pf-hit:hover { fill: color-mix(in oklab, var(--pf-accent) 25%, transparent); }
-.pf-custom .pf-hit.selected { fill: color-mix(in oklab, var(--pf-accent) 45%, transparent); stroke: var(--pf-accent); }
+/* Selected is the SOLID accent, not a wash of it. A translucent accent lands on a
+   different value in each theme — pale over the light background, dark over the
+   dark one — so no single label colour is readable on both. Solid accent is one
+   colour in both, which is what makes --pf-on-accent below a rule rather than a
+   guess. A widget that would rather tint its own region overrides with `style`. */
+.pf-custom .pf-hit.selected { fill: var(--pf-accent); stroke: var(--pf-accent); }
+/* A label NESTED inside the region — the structure to recommend, because it is the
+   only one where the rail can keep the text readable as the region changes colour
+   underneath it. `fill` inherits, so without these the label takes the region's OWN
+   fill: grey on grey at rest, and accent on accent once selected. `stroke` inherits
+   too, and that one is worse than it looks: the region's outline colour gets painted
+   around every glyph, which at label sizes is most of the glyph — pale ghosts of the
+   numbers at rest, blue ones when selected. Hence stroke: none, not just a fill. */
+:where(.pf-custom) :where(.pf-hit) text { fill: var(--pf-text-2); stroke: none; }
+.pf-custom .pf-hit.selected text { fill: var(--pf-on-accent); }
 .pf-custom .pf-drag { touch-action: none; }
 .pf-custom-error {
   margin: 4px 0; padding: 6px 8px; border: 1px solid var(--pf-err); border-radius: var(--pf-radius-control);