beenull/ladybird
1
0
Fork 0
mirror of https://github.com/LadybirdBrowser/ladybird.git synced 2024-11-21 15:10:19 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

Documentation: Document the CSS JSON files and what they do
Some checks are pending
CI / Lagom (false, FUZZ, ubuntu-22.04, Linux, Clang) (push) Waiting to run
Details
CI / Lagom (false, NO_FUZZ, macos-14, macOS, Clang) (push) Waiting to run
Details
CI / Lagom (false, NO_FUZZ, ubuntu-22.04, Linux, GNU) (push) Waiting to run
Details
CI / Lagom (true, NO_FUZZ, ubuntu-22.04, Linux, Clang) (push) Waiting to run
Details
Package the js repl as a binary artifact / build-and-package (macos-14, macOS, macOS-universal2) (push) Waiting to run
Details
Package the js repl as a binary artifact / build-and-package (ubuntu-22.04, Linux, Linux-x86_64) (push) Waiting to run
Details
Run test262 and test-wasm / run_and_update_results (push) Waiting to run
Details
Lint Code / lint (push) Waiting to run
Details
Push notes / build (push) Waiting to run
Details

Browse source
This commit is contained in:
Sam Atkins 2024-09-11 13:02:33 +01:00 committed by Andreas Kling
parent 229b64a4b7
commit 71d977b791
Notes: github-actions[bot] 2024-09-11 13:53:23 +00:00 
Author: https://github.com/AtkinsSJ
Commit: https://github.com/LadybirdBrowser/ladybird/commit/71d977b7912
Pull-request: https://github.com/LadybirdBrowser/ladybird/pull/1370
2 changed files with 171 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

170
Documentation/Browser/CSSGeneratedFiles.md Normal file
View file

@ -0,0 +1,170 @@
# CSS Generated Files
We generate a significant amount of CSS-related code, taking in one or more .json files in
[`Userland/Libraries/LibWeb/CSS`](../../Userland/Libraries/LibWeb/CSS) and producing C++ code from them, located in
`Build/<build-preset>/Lagom/Userland/Libraries/LibWeb/CSS/`.
It's likely that you'll need to work with these if you add or modify a CSS property or its values.
The generators are found in [`Meta/Lagom/Tools/CodeGenerators/LibWeb`](../../Meta/Lagom/Tools/CodeGenerators/LibWeb).
They are run automatically as part of the build, and most of the time you can ignore them.
## Properties.json
Each CSS property has an entry here, which describes what values it accepts, whether it's inherited, and similar data.
This generates `PropertyID.h` and `PropertyID.cpp`.
Most of this data is found in the information box for that property in the relevant CSS spec.
The file is organized as a single JSON object, with keys being property names, and the values being the data for that property.
Each property will have some set of these fields on it:
| Field | Required | Default | Description | Generated functions |
|----------------------------|----------|---------|-------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------|
| `affects-layout` | No | `true` | Boolean. Whether changing this property will invalidate the element's layout. | `bool property_affects_layout(PropertyID)` |
| `affects-stacking-context` | No | `false` | Boolean. Whether this property can cause a new stacking context for the element. | `bool property_affects_stacking_context(PropertyID)` |
| `animation-type` | Yes | | String. How the property should be animated. Defined by the spec. See below. | `AnimationType animation_type_from_longhand_property(PropertyID)` |
| `inherited` | Yes | | Boolean. Whether the property is inherited by its child elements. | `bool is_inherited_property(PropertyID)` |
| `initial` | Yes | | String. The property's initial value if it is not specified. | `NonnullRefPtr<CSSStyleValue> property_initial_value(JS::Realm&, PropertyID)` |
| `logical-alias-for` | No | Nothing | String. The name of a property this is an alias for. | |
| `longhands` | No | `[]` | Array of strings. If this is a shorthand, these are the property names that it expands out into. | `Vector<PropertyID> longhands_for_shorthand(PropertyID)` |
| `max-values` | No | `1` | Integer. How many values can be parsed for this property. eg, `margin` can have up to 4 values. | `size_t property_maximum_value_count(PropertyID)` |
| `percentages-resolve-to` | No | Nothing | String. What type percentages get resolved to. eg, for `width` percentages are resolved to `length` values. | `Optional<ValueType> property_resolves_percentages_relative_to(PropertyID)` |
| `quirks` | No | `[]` | Array of strings. Some properties have special behavior in "quirks mode", which are listed here. See below. | `bool property_has_quirk(PropertyID, Quirk)` |
| `valid-identifiers` | No | `[]` | Array of strings. Which keywords the property accepts. Consider defining an enum instead and putting its name in the `valid-types` array. | `bool property_accepts_keyword(PropertyID, Keyword)` |
| `valid-types` | No | `[]` | Array of strings. Which value types the property accepts. See below. | `bool property_accepts_type(PropertyID, ValueType)` |
### `animation-type`
The [Web Animations spec](https://www.w3.org/TR/web-animations/#animation-type) defines the valid values here:
| Spec term | JSON value |
|-------------------|---------------------|
| not animatable | `none` |
| discrete | `discrete` |
| by computed value | `by-computed-value` |
| repeatable list | `repeatable-list` |
| (See prose) | `custom` |
### `quirks`
The [Quirks spec](https://quirks.spec.whatwg.org/#css) defines these.
| Spec term | JSON value |
|------------------------------|----------------------|
| The hashless hex color quirk | `hashless-hex-color` |
| The unitless length quirk | `unitless-length` |
### `valid-types`
The `valid-types` array lists the names of CSS value types, as defined in the latest
[CSS Values and Units spec](https://www.w3.org/TR/css-values/), without the `<>` around them.
For numeric types, we use the [bracketed range notation](https://www.w3.org/TR/css-values-4/#css-bracketed-range-notation),
for example `width` can take any non-negative length, so it has `"length [0,∞]"` in its `valid-types` array.
## Keywords.json
This is a single JSON array of strings, each of which is a CSS keyword, for example `auto`, `none`, `medium`, or `currentcolor`.
This generates `Keyword.h` and `Keyword.cpp`.
All keyword values used by any property or media-feature need to be defined here.
The generated code provides:
- A `Keyword` enum as used by `CSSKeywordValue`
- `Optional<Keyword> keyword_from_string(StringView)` to attempt to convert a string into a Keyword
- `StringView string_from_keyword(Keyword)` to convert a Keyword back into a string
- `bool is_css_wide_keyword(StringView)` which returns whether the string is one of the special "CSS-wide keywords"
## Enums.json
This is a single JSON object, with enum names as keys and the values being arrays of keyword names.
This generates `Enums.h` and `Enums.cpp`.
We often want to define an enum that's a set of a few keywords.
`Enums.json` allows you to generate these enums automatically, along with functions to convert them to and from a Keyword,
or convert them to a string.
These enums also can be used in property definitions in `Properties.json` by putting their name in the `valid-types` array.
This helps reduce repetition, for example the `border-*-style` properties all accept the same set of keywords, so they
are implemented as a `line-style` enum.
The generated code provides these for each enum, using "foo" as an example:
- A `Foo` enum for its values
- `Optional<Foo> keyword_to_foo(Keyword)` to convert a `Keyword` to a `Foo`
- `Keyword to_keyword(Foo)` to convert the `Foo` back to a `Keyword`
- `StringView to_string(Foo)` to convert the `Foo` directly to a string
## PseudoClasses.json
This is a single JSON object, with selector pseudo-class names as keys and the values being objects with fields for the pseudo-class.
This generates `PseudoClass.h` and `PseudoClass.cpp`.
Each entry has a single required property, `argument`, which is a string containing the grammar for the pseudo-class's
function parameters - for identifier-style pseudo-classes it is left blank.
The grammar is taken directly from the spec.
The generated code provides:
- A `PseudoClass` enum listing every pseudo-class name
- `Optional<PseudoClass> pseudo_class_from_string(StringView)` to parse a string as a `PseudoClass` name
- `StringView pseudo_class_name(PseudoClass)` to convert a `PseudoClass` back into a string
- The `PseudoClassMetadata` struct which holds a representation of the data from the JSON file
- `PseudoClassMetadata pseudo_class_metadata(PseudoClass)` to retrieve that data
## MediaFeatures.json
This is a single JSON object, with media-feature names as keys and the values being objects with fields for the media-feature.
This generates `MediaFeatureID.h` and `MediaFeatureID.cpp`.
A `<media-feature>` is a value that a media query can inspect.
They are listed in the [`@media` descriptor table](https://www.w3.org/TR/mediaqueries-5/#media-descriptor-table) in the latest Media Queries spec.
The definitions here are like a simplified version of the `Properties.json` definitions.
| Field | Description |
|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `type` | String. How the media-feature is evaluated, either `discrete` or `range`. |
| `values` | Array of strings. These are directly taken from the spec, with keywords as they are, and `<>` around type names. Types may be `<boolean>`, `<integer>`, `<length>`, `<ratio>`, or `<resolution>`. |
The generated code provides:
- A `MediaFeatureValueType` enum listing the possible value types
- A `MediaFeatureID` enum, listing each media-feature
- `Optional<MediaFeatureID> media_feature_id_from_string(StringView)` to convert a string to a `MediaFeatureID`
- `StringView string_from_media_feature_id(MediaFeatureID)` to convert a `MediaFeatureID` back to a string
- `bool media_feature_type_is_range(MediaFeatureID)` returns whether the media feature is a `range` type, as opposed to a `discrete` type
- `bool media_feature_accepts_type(MediaFeatureID, MediaFeatureValueType)` returns whether the media feature will accept values of this type
- `bool media_feature_accepts_keyword(MediaFeatureID, Keyword)` returns whether the media feature accepts this keyword
## MathFunctions.json
This is a single JSON object, describing each [CSS math function](https://www.w3.org/TR/css-values/#math-function),
with the keys being the function name and the values being objects describing that function's properties.
This generates `MathFunctions.h` and `MathFunctions.cpp`.
Each entry currently has a single property, `parameters`, which is an array of parameter definition objects.
Parameter definitions have the following properties:
| Field | Description |
|------------|----------------------------------------------------------------------------------|
| `name` | String. Name of the parameter, as given in the spec. |
| `type` | String. Accepted types for the parameter, as a single string, separated by `\|`. |
| `required` | Boolean. Whether this parameter is required. |
The generated code provides:
- A `MathFunction` enum listing the math functions
- The implementation of the CSS Parser's `parse_math_function()` method
## TransformFunctions.json
This is a single JSON object, describing each [CSS transform function](https://www.w3.org/TR/css-transforms/#transform-functions),
with the keys being the function name and the values being objects describing that function's properties.
This generates `TransformFunctions.h` and `TransformFunctions.cpp`.
Each entry currently has a single property, `parameters`, which is an array of parameter definition objects.
Parameter definitions have the following properties:
| Field | Description |
|------------|----------------------------------------------|
| `type` | String. Accepted type for the parameter. |
| `required` | Boolean. Whether this parameter is required. |
The generated code provides:
- A `TransformFunction` enum listing the transform functions
- `Optional<TransformFunction> transform_function_from_string(StringView)` to parse a string as a `TransformFunction`
- `StringView to_string(TransformFunction)` to convert a `TransformFunction` back to a string
- `TransformFunctionMetadata transform_function_metadata(TransformFunction)` to obtain metadata about the transform function, such as its parameter list

2
Documentation/README.md
View file

@ -36,4 +36,4 @@ you are welcome to ask on [Discord](../README.md#get-in-touch-and-participate).
* [LibWeb: From Loading to Painting](Browser/LibWebFromLoadingToPainting.md)
* [How to Add an IDL File](Browser/AddNewIDLFile.md)
* [LibWeb Code Style & Patterns](Browser/Patterns.md)
* [CSS Generated Files](Browser/CSSGeneratedFiles.md)