Document Kryon CSS and run conformance in CI
This commit is contained in:
1 parent
240cf61ab6
commit
89a0a8b174
3 files changed
+134
-54
No files matched your search
@@ -12,7 +12,7 @@ jobs:
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
with:
|
||||
path: kss
|
||||
path: css
|
||||
|
||||
- name: Build the ziran launcher
|
||||
run: |
|
||||
@@ -21,20 +21,26 @@ jobs:
|
||||
echo "$PWD/ziran/build/bin" >> "$GITHUB_PATH"
|
||||
|
||||
- name: Test
|
||||
working-directory: kss
|
||||
working-directory: css
|
||||
run: |
|
||||
ziran fetch --locked
|
||||
make test style-pack-check
|
||||
|
||||
# C, C++, Go, ZX and the browser export must agree; Android runs
|
||||
# where a phone is attached, so it is skipped here.
|
||||
- name: Conformance
|
||||
working-directory: css
|
||||
run: env -u DISPLAY -u WAYLAND_DISPLAY make conformance
|
||||
|
||||
# A failure names the seed; rerun it with make fuzz FUZZ_SEED=N.
|
||||
- name: Fuzz with this run's seed
|
||||
working-directory: kss
|
||||
working-directory: css
|
||||
run: env -u DISPLAY -u WAYLAND_DISPLAY make fuzz FUZZ_SEED=${{ github.run_number }} FUZZ_COUNT=10000
|
||||
|
||||
- name: Keep a failing sheet
|
||||
if: failure()
|
||||
uses: actions/upload-artifact@v7
|
||||
with:
|
||||
name: kss-fuzz-failure
|
||||
path: kss/build/kss-fuzz/failure-*.kss
|
||||
name: css-fuzz-failure
|
||||
path: css/build/css-fuzz/failure-*
|
||||
if-no-files-found: ignore
|
||||
@@ -1,63 +1,134 @@
|
||||
# KSS
|
||||
# Kryon CSS
|
||||
|
||||
KSS is the style sheet language of [Kryon](https://github.com/kryonlabs/kryon)
|
||||
applications. This package parses and formats `.kss` sheets, resolves their
|
||||
`@import`s and color tokens, installs the rules into Kryon's style table, and
|
||||
ships the classic, lightfield, and material style packs in `styles/`. Kryon
|
||||
itself only resolves installed rules; apps that read `.kss` text add this
|
||||
package.
|
||||
Kryon applications are styled with a subset of CSS. This package parses
|
||||
`.css` sheets into Kryon's style table, compiles style packs into tables apps
|
||||
load without parsing, formats sheets, exports them to browser CSS for
|
||||
Kryon's document host, and converts old KSS sheets. It ships the classic,
|
||||
lightfield and material packs in `styles/`. The same table drives every
|
||||
Kryon backend: desktop, console, Android, the web canvas and DOM hosts, and
|
||||
apps built through the C, C++ and Go targets.
|
||||
|
||||
## Use it
|
||||
|
||||
```sh
|
||||
ziran add https://github.com/kryonlabs/kss.git
|
||||
ziran add https://github.com/kryonlabs/css.git
|
||||
```
|
||||
|
||||
```zi
|
||||
using Styles :: #import "kss/Kss";
|
||||
#import "kss/SystemStyle"
|
||||
using Styles :: #import "css/Css";
|
||||
#import "css/SystemStyle"
|
||||
|
||||
sheet: CssSheet;
|
||||
|
||||
Start :: () {
|
||||
if !CssSheetLoad(*sheet, StylePackClassic()) { return }
|
||||
if CssSheetParse(*sheet, app_css, "app.css", CssNoImports) {
|
||||
CssSheetInstall(*sheet, CssDefaultEnvironment(), null)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`BeginStyleRules`, `ParseStyleRules`, and `InstallParsedStyleRules` parse a
|
||||
sheet in steps and install it; `ProvideStyleRulesImport` answers an
|
||||
`@import`. `SystemStyle` picks a pack that matches the desktop theme. The
|
||||
classic pack is also compiled in as `style_pack_classic`, so an app can
|
||||
install it without shipping the `.kss` file.
|
||||
A sheet is parsed whole or not at all: `CssSheetParse` returns false with a
|
||||
diagnostic such as `unknown property 'colr' at app.css:2:3`
|
||||
(`CssSheetDiagnostic`). `CssSheetInstall` resolves `var()` for an
|
||||
environment and installs the rules and color custom properties together; on
|
||||
failure the previous style stays. `CssSheetBuild` fills a `StyleRules` table
|
||||
without installing it, and `CssSheetToken` reads a custom property's value.
|
||||
`CssOverrideColor` and `CssOverrideLength` let a host override custom
|
||||
properties (`--accent`, for example) for one install. `SystemStyle`
|
||||
installs the classic pack with colors that follow the desktop theme.
|
||||
|
||||
Customization hosts can use `KssAddTokenOverride` before parsing to override
|
||||
color, length, duration, or material tokens throughout a pack. A later override
|
||||
of the same name and kind replaces the earlier value. Names are owned by the
|
||||
parser; invalid names and exhausted capacity produce diagnostics. Rule
|
||||
installation validates the new snapshot before replacing existing colors.
|
||||
Imports go through a resolver you pass: `(name: string) -> CssImportAnswer`.
|
||||
Hosts without imports pass `CssNoImports`.
|
||||
|
||||
## The subset
|
||||
|
||||
Selectors are a widget type (`Button`, `TextField`, `App`, `*`), classes
|
||||
(`.primary`), Kryon attributes (`[role=Label]`, `[tone=Accent]`,
|
||||
`[emphasis=Soft]`) and one state: `:hover`, `:active`, `:focus`,
|
||||
`:focus-visible`, `:disabled`, `:selected`, `:checked` or `:loading`, in
|
||||
comma lists. Combinators and nesting are outside the subset.
|
||||
|
||||
Properties: `color`, `background` (a color or a two-stop
|
||||
`linear-gradient`), `background-color`, `border`, `border-color`,
|
||||
`border-width`, `border-style` (`solid` or `none`), `border-radius`,
|
||||
`outline-color`, `opacity`, `padding` (one or two values),
|
||||
`padding-inline`, `padding-block`, `gap`, `font-size`, `font-family`,
|
||||
`letter-spacing`, `translate`, `-kryon-material` (`lightfield`, `flat`,
|
||||
`glass`) and `-kryon-icon-size`. Document layout properties (`width`,
|
||||
`margin`, `display`, `transition` and the like) are kept for the web
|
||||
document host and skipped by native hosts.
|
||||
|
||||
Values: hex, named, `rgb()`, `rgba()`, `hsl()` and `hsla()` colors; `px`
|
||||
and `rem` (16px) lengths; `s` and `ms` durations; `var(--name, fallback)`.
|
||||
`em` and `%` lengths are errors, because Kryon has no inherited font size
|
||||
or containing block. Custom properties are declared in `:root`.
|
||||
|
||||
At-rules: `@import` (before other rules), `@layer` statements and blocks,
|
||||
`@media` with `prefers-color-scheme`, `prefers-contrast`, `pointer`,
|
||||
`min-width` and `max-width`, plus Kryon's `-kryon-theme`, `-kryon-density`,
|
||||
`-kryon-pointer` and `-kryon-platform` features, and `@keyframes`.
|
||||
`!important`, escapes and `//` comments are errors.
|
||||
|
||||
Rules rank by layer (unlayered rules last), then Kryon's specificity, then
|
||||
source order. Kryon's specificity counts a widget type 1, each attribute 10,
|
||||
a class 20 and a name 100; states add nothing, because a widget is in one
|
||||
state at a time (disabled, loading, pressed, hovered, selected, focused, in
|
||||
that order of precedence).
|
||||
|
||||
## Style packs
|
||||
|
||||
`styles/NAME.css` is compiled into `src/style_pack_NAME.zi`, a table of
|
||||
words `CssSheetLoad(*sheet, StylePackNAME())` appends without parsing.
|
||||
After editing a pack, run `make style-packs` and commit the module with it;
|
||||
`make style-pack-check` fails when a module no longer matches its CSS or the
|
||||
CSS is not formatted.
|
||||
|
||||
## Formatting
|
||||
|
||||
`CssFormat(source, output)` writes one declaration per line with two-space
|
||||
indentation. It refuses a sheet that does not parse, and checks that the
|
||||
formatted sheet parses to the same rules. `make format FILES="a.css"` runs
|
||||
it on files.
|
||||
|
||||
## Browser CSS
|
||||
|
||||
`ExportCSS(source, path, environment, output)` writes CSS for Kryon's DOM
|
||||
host. Selectors are scoped under `#kryon-dom-root` and matched against the
|
||||
`data-kryon-widget`, `data-kryon-class` and ARIA attributes the host
|
||||
writes; custom properties go on the root, `-kryon-*` declarations are
|
||||
dropped, environment media queries are decided for `environment`, and
|
||||
viewport queries stay for the browser. Every selector is wrapped in
|
||||
`:where()` and rules are written in Kryon's priority order, so the browser
|
||||
ranks them as native hosts do. Attribute selectors and unresolved imports
|
||||
are refused with a message, never exported in part. `StyleClass(name)`
|
||||
returns the class ID Kryon widget props take.
|
||||
|
||||
## From KSS
|
||||
|
||||
KSS, the earlier style language, is no longer read. `make migrate
|
||||
IN=old.kss OUT=new.css` converts a sheet, and `CssMigrateKss(source,
|
||||
output)` converts saved sheets in apps. Tokens become `:root` custom
|
||||
properties, `@theme` becomes a media query, `foreground` becomes `color`,
|
||||
`padding-x` and `padding-y` become `padding-inline` and `padding-block`,
|
||||
`radius` becomes `border-radius`, `:pressed` becomes `:active`,
|
||||
unitless numbers become `px`, and `[class=x]` becomes `.x`. A construct with
|
||||
no CSS form, such as `@variant`, is an error naming its line.
|
||||
|
||||
## Develop
|
||||
|
||||
`ExportCSS(source, path, environment, output)` exports a supplied KSS source
|
||||
unit to CSS for Kryon's document host. Use the bytes through `result.count`
|
||||
only when `result.ok` is true. `StyleClass(name)` returns the class ID accepted
|
||||
by Kryon widget props. The exporter shares the parser, token resolution and
|
||||
environment rules; widget/class/state selectors become scoped DOM selectors,
|
||||
numeric units and axis properties are expanded, and media conditions survive.
|
||||
Source and saved IR run on C, C++ and Go in `tests/css_export_test.sh`.
|
||||
The C++ host compiles Ziran's generated C output as C++17.
|
||||
`make check` runs the behavior tests, the conformance test, the style pack
|
||||
check and the fuzzer. The conformance test (`tests/css_conformance.sh`)
|
||||
builds each pack with an app sheet over it and requires the same digest of
|
||||
the rule table and every resolved widget style from the C program, a C++
|
||||
host, the Go target, a ZX bundle and, when a phone is on adb and the NDK is
|
||||
installed, an Android build. It then checks the browser export of the app
|
||||
sheet value by value in headless Chromium. `make fuzz FUZZ_SEED=N
|
||||
FUZZ_COUNT=M` runs generated and damaged sheets under AddressSanitizer and
|
||||
UndefinedBehaviorSanitizer; a failing sheet is kept in `build/css-fuzz/`.
|
||||
|
||||
The current export subset rejects unresolved imports, KSS layers, nested
|
||||
selector functions, native materials, unknown foreign blocks and output
|
||||
overflow. Resolve imports or flatten layers before export. Unsupported output
|
||||
is reported explicitly rather than producing a usable partial sheet. Browser
|
||||
CSS keywords and authored units remain literal values. Native-only effects
|
||||
such as gradient endpoints and materials need an explicit browser stylesheet.
|
||||
|
||||
`make check` checks the package, runs the parser and style tests as portable
|
||||
bundles and native code, verifies that `src/style_pack_classic.zi` matches
|
||||
`styles/classic.kss`, and fuzzes generated and damaged sheets under
|
||||
AddressSanitizer and UndefinedBehaviorSanitizer. After editing
|
||||
`styles/classic.kss`, run `make style-packs` and commit the regenerated
|
||||
module with it. `make fuzz FUZZ_SEED=N FUZZ_COUNT=M` runs other sheets; a
|
||||
failing one is kept in `build/kss-fuzz/` with a command that shrinks it.
|
||||
|
||||
To test against the local compiler and Kryon checkouts, put this in an
|
||||
ignored `ziran.local.toml`:
|
||||
To test against local compiler and Kryon checkouts, put this in an ignored
|
||||
`ziran.local.toml`:
|
||||
|
||||
```toml
|
||||
[overrides]
|
||||
|
||||
@@ -63,11 +63,14 @@ same Go "$OUT/go.txt"
|
||||
# ZX: the bundle returns the combined digest.
|
||||
"$ZIRAN" bundle --project --entry css_conformance:CssConformanceAll -o "$OUT/conformance.zx" \
|
||||
tests/css_conformance.zi 2>&1 | quiet
|
||||
# The bundle is run by the toolchain that wrote it, the project's own.
|
||||
ZX_RUN="$ZIRAN"
|
||||
# The bundle is run by the toolchain that wrote it, the project's own; where
|
||||
# that is not built, the portable runtime runs the entry from source.
|
||||
TOOLCHAIN="$("$ZIRAN" pkg path ziran 2> /dev/null)/build/bin/ziran"
|
||||
if [ -x "$TOOLCHAIN" ]; then ZX_RUN="$TOOLCHAIN"; fi
|
||||
echo "all $("$ZX_RUN" run "$OUT/conformance.zx")" > "$OUT/zx.txt"
|
||||
if [ -x "$TOOLCHAIN" ]; then
|
||||
echo "all $("$TOOLCHAIN" run "$OUT/conformance.zx")" > "$OUT/zx.txt"
|
||||
else
|
||||
echo "all $("$ZIRAN" run --entry css_conformance:CssConformanceAll tests/css_conformance.zi 2>&1 | quiet)" > "$OUT/zx.txt"
|
||||
fi
|
||||
if ! grep -qx "$(cat "$OUT/zx.txt")" "$EXPECTED"; then
|
||||
echo "css conformance: ZX printed '$(cat "$OUT/zx.txt")', expected the 'all' line of $EXPECTED" >&2
|
||||
exit 1
|
||||
|
||||
Reference in new issue
Block a user