archaeopteryx 3.27.0 → 3.28.0

package/README.md

@@ -1213,6 +1213,86 @@ for the tree it moves to, and so does a new launch. A launch that is rejected
 while an earlier viewer is still on the page leaves that viewer's report as
 it was and adds one line saying what failed.
 
+### The host page's stylesheet
+
+The viewer is drawn inside your page, in your page's document, so your
+stylesheet applies to it. A rule written for something else can reach it: on
+one site, `.Phylogeny svg { background: #FFFFFF }`, written when the tree was
+the only svg in that box, put a white square behind every icon of the control
+panel. The viewer now says for itself what it used to leave to the page:
+
+* **Everything it puts on the page starts from the browser's own defaults.**
+  The control panel, the dialogs, the menus, the tooltip, the "working" card
+  and the alignment bar are untouched by rules written with element names
+  only, whichever stylesheet comes first: a reset's `* { box-sizing:
+  border-box }`, a framework's `label { font-weight: 700 }` or `button { font:
+  inherit }`, `svg { fill: currentColor }`. And a sheet's `:focus { outline:
+  0 }` no longer takes the keyboard focus ring off the viewer's controls.
+* **What your page hands down by inheritance stops at the viewer.** A page set
+  in capitals, centred, or in a serif face does not set the panel, the dialogs
+  or the tree that way.
+* **The tree's svg is `svg.aptx-tree`.** Its size and its font are stated
+  inline (a page whose only svgs were icons, with `svg { width: 24px; height:
+  24px }`, drew the tree 24 px square), and its background is a rectangle the
+  viewer draws, not the svg's own.
+* **Every shape states its paint as an inline style**, in the tree and in the
+  viewer's other svgs: its fill, its stroke, its opacity, a label's alignment.
+  An svg *attribute* gives way to any rule of the page, so a chart's
+  stylesheet written for a page with one chart on it, `path { fill: none;
+  stroke: #000 }` or `text { font: 10px sans-serif }`, used to repaint the
+  tree: its branches, its labels, its legends. What a shape does not state it
+  has from its parent, whatever the page says of a `path`, a `rect` or a
+  `text`: bare, in a state (`rect:hover`), or inside a container of yours
+  (`.chart text`). Nor does a page-wide `* { transition: all .3s }` make the
+  tree ease behind its own redraws.
+* **The icons, the logo and the clock plot** are untouched by a rule for a
+  bare `svg` inside a container of yours (`.my-box svg { ... }`).
+
+What still follows the page, on purpose: `direction`, `cursor`, `visibility`
+and `pointer-events` on whatever contains the viewer.
+
+**To restyle the viewer deliberately, name its classes**, inside a container
+of your own so that your rule outweighs the viewer's: `.my-page svg.aptx-tree
+{ border: 1px solid #ccc }` (the border fits inside the tree's size),
+`.my-page .aptx-panel { ... }`.
+
+**A shape's colours and strokes are not restyled by CSS any more.** Through
+3.27.0 a rule such as `#tree path { stroke-width: 2px }` thickened the
+branches, because their width was an attribute; an inline style gives way to
+nothing but `!important`. Colours, widths and fonts are what the
+configuration and the control panel are for; a rule that must override them
+says `!important`.
+
+**What the viewer cannot do from inside your document:**
+
+* A rule that names **a class of yours and an element** (`.content button {
+  text-transform: uppercase }`, `.page label { ... }`) still reaches the
+  viewer's buttons, labels and fields wherever the viewer's own rule for that
+  control does not state the same property: the defaults above weigh less than
+  one class, or they would outweigh the viewer's own rules. If your page has
+  such rules around the viewer, scope them to your own content.
+* For a shape it takes more: a rule with two classes of yours, or an `id`,
+  still reaches what a shape does not state itself (`.page .chart text {
+  letter-spacing: 1px }` spaces the tree's labels).
+* Where a shape is, and how large, is still in its attributes (`x`, `y`,
+  `width`, `d`, `r`, `transform`): a rule such as `rect { width: 100% }` or
+  `circle { r: 4px }` moves or resizes the viewer's shapes too.
+* Nothing outranks a rule scoped by an `id`, or marked `!important`.
+
+A file is another matter: it has no page around it. In an exported SVG file a
+shape's colours, strokes, opacities and text alignment are attributes
+(`fill="..."`, `stroke-opacity="..."`), the form every program that opens an
+svg reads; only fonts and `paint-order` are in `style`. Its colours are those
+SVG 1.1 has: what is `transparent` on the page is `none` in the file, and a
+translucent colour is the colour with a `fill-opacity` or `stroke-opacity`
+(Inkscape 1.1 draws `transparent` and `rgba(...)` as black).
+
+`test/browser/host_css.html` launches the viewer under real stylesheets (the
+BV-BRC website's, Bootstrap 3 and 5, Tailwind's reset, and a sheet of single
+rules of kinds found on real pages), each added after the viewer's own, and
+fails on any difference from a launch in a clean page: in what any element
+computes to, and in where it sits.
+
 ### Downloads
 
 The panel's **Download** section (folded until you open it) holds the choices
@@ -1263,6 +1343,11 @@ tree, with the same columns, and a table that joins back onto the tree as
 A full-size PDF taller or wider than 200 inches (14,400 pt, the PDF page
 limit) is scaled onto the largest page; it is vector, so nothing is lost.
 
+**The SVG file is written for programs other than a browser**: a shape's
+paint is in attributes, and its colours are those SVG 1.1 has (no
+`transparent`, no `rgba(...)`, which Inkscape 1.1 draws as black). See [The
+host page's stylesheet](#the-host-pages-stylesheet).
+
 Newick and Nexus files usually carry branch support as a bare internal label
 (`)100:0.05`). Archaeopteryx.js recognises those automatically and treats them
 as confidence values, so support-based features work without any setup. If your
@@ -1600,7 +1685,7 @@ All 118 of them, alphabetically:
 | `allowManualNodeSelection` | Renamed to `enableManualNodeSelection`. |
 | `backgroundColorDefault` | The background is fixed. |
 | `backgroundColorForPrintExportDefault` | The export background is fixed. |
-| `border` | Style the tree's svg with CSS instead. |
+| `border` | Style the tree's svg with CSS instead: it is `svg.aptx-tree` (a rule for a bare `svg` reaches the panel's icons too). |
 | `branchColorDefault` | The default branch colour is fixed. |
 | `branchDataFontSize` | Font size is fixed at launch (derived: 2px smaller than labels, floor 6px) and changed only via the in-panel Font slider — not a launch config key. |
 | `branchWidthDefault` | Branch width follows the size of the tree. |