.\" Automatically generated by Pandoc 3.7.0.1
.\"
.TH "CHA-CSS" "7"
.SH CSS in Chawan
This document describes CSS features supported by Chawan, as well as its
proprietary extensions and deviations from standards.
.PP
If you discover a deviation that is not covered by this document, please
open a ticket at \c
.UR https://todo.sr.ht/~bptato/chawan
.UE \c
\&.
.SS Standard properties
A list of supported standard properties, with notes on unimplemented
values:
.IP \(bu 2
background\-color (see color)
.IP \(bu 2
background\-image (displays placeholders only)
.IP \(bu 2
border\-collapse
.IP \(bu 2
border\-*\-style, border\-*\-color, border\-*\-width (but see borders)
.IP \(bu 2
border\-spacing
.IP \(bu 2
bottom
.IP \(bu 2
box\-sizing
.IP \(bu 2
caption\-side
.IP \(bu 2
clear
.IP \(bu 2
color (hex values and functions \f[CR]rgb\f[R], \f[CR]rgba\f[R],
\f[CR]hsl\f[R], \f[CR]hsla\f[R])
.IP \(bu 2
content (string, (no\-)open/close\-quote, counter())
.IP \(bu 2
counter\-increment
.IP \(bu 2
counter\-reset
.IP \(bu 2
counter\-set
.IP \(bu 2
display (\f[CR]block\f[R], \f[CR]inline\-block\f[R],
\f[CR]list\-item\f[R], \f[CR]table\f[R], \f[CR]table\-*\f[R],
\f[CR]flex\f[R], \f[CR]inline\-flex\f[R], \f[CR]flow\-root\f[R])
.IP \(bu 2
flex\-basis (but \f[CR]content\f[R] not supported)
.IP \(bu 2
flex\-direction
.IP \(bu 2
flex\-grow
.IP \(bu 2
flex\-shrink
.IP \(bu 2
flex\-wrap
.IP \(bu 2
float
.IP \(bu 2
font\-size (ignored; only for JS compatibility)
.IP \(bu 2
font\-style (\f[CR]oblique\f[R] interpreted as \f[CR]italic\f[R])
.IP \(bu 2
font\-weight (numeric properties > 500 interpreted as bold, others as
regular)
.IP \(bu 2
height
.IP \(bu 2
left
.IP \(bu 2
list\-style\-position
.IP \(bu 2
list\-style\-type (but no custom list styles)
.IP \(bu 2
margin\-bottom
.IP \(bu 2
margin\-left
.IP \(bu 2
margin\-right
.IP \(bu 2
margin\-top
.IP \(bu 2
max\-height
.IP \(bu 2
max\-width
.IP \(bu 2
min\-height
.IP \(bu 2
min\-width
.IP \(bu 2
opacity (hacky; only works with \f[CR]opacity: 0\f[R])
.IP \(bu 2
overflow\-x (see below on scrollbars)
.IP \(bu 2
overflow\-y (see below on scrollbars)
.IP \(bu 2
padding\-bottom
.IP \(bu 2
padding\-left
.IP \(bu 2
padding\-right
.IP \(bu 2
padding\-top
.IP \(bu 2
position (see below for \f[CR]sticky\f[R] and \f[CR]fixed\f[R])
.IP \(bu 2
quotes
.IP \(bu 2
right
.IP \(bu 2
text\-align
.IP \(bu 2
text\-decoration (\f[CR]none\f[R], \f[CR]underline\f[R],
\f[CR]overline\f[R], \f[CR]line\-through\f[R])
.IP \(bu 2
text\-transform
.IP \(bu 2
top
.IP \(bu 2
vertical\-align
.IP \(bu 2
visibility
.IP \(bu 2
white\-space
.IP \(bu 2
width
.IP \(bu 2
word\-break
.IP \(bu 2
z\-index
.PP
Shorthands:
.IP \(bu 2
all
.IP \(bu 2
margin
.IP \(bu 2
padding
.IP \(bu 2
border, border\-style, border\-color, border\-width (but see borders)
.IP \(bu 2
background (only color and url; other components are skipped)
.IP \(bu 2
list\-style (list\-style\-image is skipped)
.IP \(bu 2
flex
.IP \(bu 2
flex\-flow
.IP \(bu 2
overflow
.PP
Variables (the \f[CR]var()\f[R] function) are fully supported.
.PP
Values of \f[CR]<length>\f[R] or \f[CR]<color>\f[R] types fully support
\f[CR]calc()\f[R] expressions.
.SS Selectors
All selector types from CSS 2.1 are supported, except for namespaces.
.PP
Following standard pseudo\-classes are supported:
\f[CR]:first\-child\f[R], \f[CR]:last\-child\f[R],
\f[CR]:only\-child\f[R], \f[CR]:hover\f[R], \f[CR]:root\f[R],
\f[CR]:nth\-child()\f[R], \f[CR]:nth\-last\-child()\f[R],
\f[CR]:checked\f[R], \f[CR]:focus\f[R], \f[CR]:is()\f[R],
\f[CR]:not()\f[R], \f[CR]:where()\f[R], \f[CR]:lang()\f[R],
\f[CR]:link\f[R], \f[CR]:target\f[R], \f[CR]:disabled\f[R].
.PP
\f[CR]:visited\f[R] is parsed, but for now it is not matched.
.PP
\f[CR]:defined\f[R], \f[CR]:host\f[R], and \f[CR]:host()\f[R] are
matched for compatibility; however, custom elements and shadow DOM are
not supported yet.
.PP
The standard pseudo\-elements \f[CR]::before\f[R], \f[CR]::after\f[R],
and \f[CR]::marker\f[R] are supported.
\f[CR]::backdrop\f[R] is parsed for compatibility, but is not supported
yet.
.SS At\-rules
Following rules starting with an \f[CR]\(at\f[R] sign are supported.
.SS \f[CR]\(atmedia\f[R]
The \f[CR]grid\f[R], \f[CR]hover\f[R],
\f[CR]prefers\-color\-scheme\f[R], \f[CR]scripting\f[R],
\f[CR]width\f[R], and \f[CR]height\f[R] media features are fully
supported.
.PP
The \f[CR]color\f[R], \f[CR]color\-index\f[R], and \f[CR]monochrome\f[R]
features are supported, but only consider the number of supported text
colors (which can differ from the number of colors in Sixel/Kitty
images).
.SS \f[CR]\(atimport\f[R]
Importing to layers is supported.
.PP
\f[CR]\(atimport\f[R] combined with media queries is not yet supported.
.SS \f[CR]\(atlayer\f[R]
\f[CR]\(atlayer\f[R] is fully supported.
(I think.)
.SS Proprietary extensions
.IP \(bu 2
\f[CR]text\-align\f[R] accepts the values \f[CR]\-cha\-center\f[R],
\f[CR]\-cha\-left\f[R], and \f[CR]\-cha\-right\f[R] to support the HTML
\f[CR]<center>\f[R], \f[CR]<div align=left>\f[R] and
\f[CR]<div align=right>\f[R] elements.
(Analogous to \f[CR]\-moz\-center\f[R] etc.)
.IP \(bu 2
Properties with a \f[CR]<color>\f[R] value accept the function
\f[CR]\-cha\-ansi()\f[R], mapping to terminal\-specific (\(lqANSI\(rq)
colors.
The function takes one of
.RS 2
.IP \(bu 2
An 8\-bit integer, indicating a color value as set by XTerm\(cqs indexed
color feature.
.IP \(bu 2
One of the strings \(lqblack\(rq, \(lqred\(rq, \(lqgreen\(rq,
\(lqyellow\(rq, \(lqblue\(rq, \(lqmagenta\(rq, \(lqcyan\(rq,
\(lqwhite\(rq for an ANSI color, possibly prefixed by the string
\(lqbright\-\(rq to indicate an aixterm 16\-color value.
.RE
.IP \(bu 2
\f[CR]text\-decoration\f[R] accepts the keyword
\f[CR]\-cha\-reverse\f[R], which sets the \f[I]reverse video\f[R]
parameter on the text.
(This is used by the UA style sheet to highlight text in
\f[CR]<code>\f[R] tags.)
.IP \(bu 2
\f[CR]text\-transform\f[R] accepts the keyword
\f[CR]\-cha\-half\-width\f[R], which has the opposite effect as
\f[CR]full\-width\f[R].
.RS 2
.PP
This can be used in user style sheets to compress distracting ruby text:
\f[CR]rt{text\-transform: \-cha\-half\-width}\f[R].
Characters without half\-width counterparts are left intact, except
hiragana is treated as katakana.
.RE
.IP \(bu 2
The \f[CR]\-cha\-colspan\f[R] and \f[CR]\-cha\-rowspan\f[R] properties
have the same effect as the \f[CR]colspan\f[R] and \f[CR]rowspan\f[R]
attributes on tables.
.IP \(bu 2
The \f[CR]:\-cha\-first\-node\f[R] and \f[CR]:\-cha\-last\-node\f[R]
pseudo\-classes apply to elements that have no preceding/subsequent
sibling node that is either an element node or a text node with
non\-whitespace contents.
(Modeled after \f[CR]:\-moz\-first\-node\f[R] and
\f[CR]:\-moz\-last\-node\f[R].)
.IP \(bu 2
If \f[CR]buffer.mark\-links\f[R] is set, the
\f[CR]::\-cha\-link\-marker\f[R] pseudo\-element will be generated on
all anchor elements.
.IP \(bu 2
In hints mode (by default, the \f[CR]f\f[R] key) the markers are
implemented by generating \f[CR]::\-cha\-link\-hint\f[R] on all
applicable elements.
So you can change the marker background in your \f[CR]user\-style\f[R]
(\f[CR][buffer]\f[R] section in \f[CR]config.toml\f[R]):
.RS 2
.IP
.EX
\f[BI]::\-cha\-link\-hint\f[R] { \f[B]background\f[R]: gainsboro }
.EE
.RE
.IP \(bu 2
The \f[CR]\-cha\-content\-type\f[R] media feature can be used to filter
documents for their content type.
For example, you can add
.RS 2
.IP
.EX
\f[B]\(atmedia\f[R] (\-cha\-content\-type: \(dqtext/markdown\(dq) { body { \f[B]width\f[R]: 80ch } }
.EE
.PP
to your \f[CR]user\-style\f[R] to set the body width of all markdown
documents to 80 characters.
(The string is matched case\-insensitively.)
.RE
.SS Rendering quirks
These are willful violations of the standard, usually made to better fit
the display model inherent to projecting the web to a cell\-based
screen.
.SS User agent style sheet
The user agent style sheet is a combination of the styles suggested by
the HTML standard and a CSS port of w3m\(cqs rendering.
In general, faithfulness to w3m is preferred over the standard\(cqs
suggestions, unless w3m\(cqs rendering breaks on existing websites.
.PP
Link colors differ depending on the terminal\(cqs color scheme.
.SS Sizing and positioning
Layout is performed on a finite canvas of coordinates represented by a
32\-bit fixed\-point number with 6 bits of precision.
After layout, these positions are divided by the cell width and/or
height, with the fractional part truncated.
(This is subject to change.)
.PP
In case of Kitty images, the fractional part is preserved, and is used
as an in\-cell offset.
.PP
The lengths \f[CR]1em\f[R] and \f[CR]1ch\f[R] compute to the cell height
and cell width respectively.
.PP
In outer inline boxes (\f[CR]inline\-block\f[R],
\f[CR]inline\-flex\f[R]) and \f[CR]list\-item\f[R] boxes, margins and
padding that are smaller than one cell (on the respective axis) are
ignored.
This does not apply to blockified inline boxes.
.PP
When calculating clip boxes (\f[CR]overflow: hidden\f[R] or
\f[CR]clip\f[R]), the clip box\(cqs offset is floored, and its size is
ceiled to the nearest cell\(cqs boundaries.
This means that \(lqwidth: 1px; overflow: hidden\(rq will still display
the first character of a text box.
.SS Scroll bars
Chawan does not have scroll bars, as they would complicate on\-page
navigation and would not work in dump mode.
Instead, the \(lqoverflow\-x/y\(rq properties are handled as follows.
.IP "1." 3
If \f[CR]overflow\f[R] is \f[CR]auto\f[R] or \f[CR]scroll\f[R], and the
intrinsic minimum size of the box is greater than its specified size,
then the former overrides the latter.
.IP "2." 3
Content that spills out of a scroll container on the X axis is
displayed, while content that spills out of a scroll container on the Y
axis is clipped.
.SS \f[CR]position: fixed\f[R], \f[CR]position: sticky\f[R]
To keep the document model static, these do not change their position
based on the viewport\(cqs scroll status.
Instead:
.IP \(bu 2
\f[CR]position: sticky\f[R] is treated as \f[CR]position: static\f[R],
except it also behaves as an absolute position container.
.IP \(bu 2
\f[CR]position: fixed\f[R] is placed at the bottom of the document.
.PP
Right now, \f[CR]position: fixed\f[R] is always positioned at the bottom
of the root element\(cqs margin box.
This breaks on pages that overflow it (e.g.
by setting \f[CR]height: 100%\f[R] on the root element), so it will be
moved to the bottom of its overflow box in the future.
.SS Color correction
Some authors only specify one of the foreground or the background color,
assuming a black\-on\-white canvas.
The \f[CR]display.minimum\-contrast\f[R] option adjusts the foreground
color so that text remains readable even if the terminal background does
not match this expectation.
(The exact algorithm is unspecified and subject to change.)
.PP
To avoid breaking spoiler mechanisms that rely on \(lqblack on black\(rq
text, color correction is not invoked on cells that have an RGB color
(typically specified by the author.)
.SS Borders
CSS borders are difficult to accurately display on a cell\-based
display.
So while the functionality exists, it has some limitations:
.IP \(bu 2
On tables, borders are always collapsed, even when
\f[CR]border\-collapse\f[R] is set to \f[CR]separate\f[R].
.IP \(bu 2
With \f[CR]border\-collapse: separate\f[R], the spacing between cells is
the largest of \f[CR]border\-spacing\f[R] times two and the cell width.
.IP \(bu 2
\f[CR]border\-*\-width\f[R] is interpreted as a binary value: a width of
0 results in no border, while any other width results in a border of a
single type.
If the width is smaller than one cell (in the respective direction), the
rest is subtracted from the margin (if there is any margin).
.IP \(bu 2
\f[CR]box\-sizing: border\-box\f[R] actually sets the padding box size,
so that borders rounded up to the cell size do not accidentally take all
space from the actual content.
(That in turn would cause problems if a child box set
\f[CR]overflow: hidden\f[R], etc.)
.SS See also
\f[B]cha\f[R](1)