Skip to content

docs: state that box-sizing defaults to border-box, unlike CSS - #39

Open
leshchenko1979 wants to merge 1 commit into
Macawls:mainfrom
leshchenko1979:docs/box-sizing-default
Open

leshchenko1979 wants to merge 1 commit into
Macawls:mainfrom
leshchenko1979:docs/box-sizing-default

Conversation

@leshchenko1979

Copy link
Copy Markdown
Contributor

Summary

box-sizing resolves to border-box when the property is absent — the opposite of the
CSS default. README.md listed both accepted values but never said which one applies when
the property is omitted, so anyone comparing Ogre output against a browser met the
divergence with no warning.

This documents it. The default is unchanged.

  • README.md — the box-sizing bullet names the default; a new ### Differences from CSS
    section under Supported CSS Properties states the divergence, the reason (Satori
    compatibility) and the explicit-value escape hatch.
  • style/resolve.go — comments at the two places that materialise the default
    (mergeProps baseline, getOr fallback) so a later reader does not "fix" it silently.

Before / after

-- `box-sizing`: content-box, border-box
+- `box-sizing`: content-box, border-box — **defaults to `border-box`, unlike CSS** (see [Differences from CSS](#differences-from-css))

Plus a new section:

Differences from CSS

One default differs from the browser, deliberately:

Property Ogre default CSS default Why
box-sizing border-box content-box Keeps the same input rendering the same here as in Satori, which is the behaviour this engine is built to match.

With border-box, width and height are outer dimensions: padding and border are drawn
inside them. <div style="width:200px;padding:0 50px"> is 200px wide here and 300px wide
in a browser.

Why document rather than change

Reported in #38 with measurements. On a 21-case Chromium comparison suite with one shared
font file, the border-box default accounts for the two largest remaining divergences
(20-boxsizing-default 1.09 %, 17-table-div 1.20 %); every other case is ≤ 0.77 % and
that residual is glyph antialiasing. Flipping the default would move every layout that
relies on it today and would break Satori-style input that omits box-sizing — a
maintainer decision, hence a docs change here and not a behaviour change.

The explicit-value half is a separate gap, tracked in #26: box-sizing: content-box is
parsed but not yet read by the layout package (grep -r BoxSizing layout/ is empty), so
the escape hatch the README now mentions starts working when that lands. This PR does not
stack on it.

Verification

  • go build ./cmd/ogre — exit 0.
  • git diff origin/main --stat — README.md, style/resolve.go only; the Go diff is
    three added comment lines, no code change.
  • The box-sizing defaults to border-box (CSS default is content-box) and the default is undocumented #38 probe <div style="width:200px;padding:0 50px;background:#f00">x</div> renders a
    byte-identical SVG from this branch and from main (md5 87b96f18fe2173e3135318763215b9c8),
    200 px wide in both.
  • style/resolve_test.go already asserts the border-box default for an unstyled div;
    untouched, and it is the lock on the decision.

Refs #38

Ogre resolves box-sizing to border-box when the property is absent, which is
the opposite of the CSS default. The README listed both accepted values
without saying which one applies when the property is omitted, so anyone
comparing Ogre output against a browser met the divergence with no warning.

- README: the box-sizing bullet names the default, and a new "Differences
  from CSS" section states the divergence, its reason (Satori compatibility)
  and the explicit-value escape hatch.
- style/resolve.go: comments at the two places that materialise the default,
  so a later reader does not "fix" it silently.

No behavioural change: the default stays border-box. The Macawls#38 probe renders
byte-identically before and after.

Refs Macawls#38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant