gioser

tawasuyu/taffy

A high performance rust-powered UI layout library

HTML 5544Rust 88Markdown 11TOML 91926 Sutichaykuna

Add morphorm style properties doc (#309)

8cdbd42cc82f840e0ff107f5ee196ac435607e50 · ruwaq Nico Burns · (3 wata ñawpaq) · tayta 8c57927d5 · kay commitpi sach'ata qhaway

Semántico sayk'uy

Mana ima sutichaypas t'ikrakurqanchu: qillqalla, yachachiylla utaq willaylla t'ikrakurqan.

1 qillqakuna · +71 −0

diff --git a/docs/morphorm-style-properties.md b/docs/morphorm-style-properties.md
new file mode 100644
index 000000000..08c2318f7
--- /dev/null
+++ b/docs/morphorm-style-properties.md
@@ -0,0 +1,71 @@
+# Morphorm Styles
+
+## Unique Types
+
+`LayoutType` (corresponds to `Display` in Taffy):
+
+```rust
+enum LayoutType {
+    Row,
+    Column,
+    Grid,
+}
+```
+
+`PositionType` (corresponds to `Position` in Taffy):
+
+```rust
+pub enum PositionType {
+    SelfDirected, // = Position::Absolute
+    ParentDirected, // = Position::Relative
+}
+```
+
+`Units` (corresponds to `Dimension` in Taffy):
+
+```rust
+pub enum Units {
+    Pixels(f32), // = Dimension::Points
+    Percentage(f32), // = Dimension::Percent
+    Auto, // = Dimension::Auto
+    Stretch(f32), // No equivalent in Taffy!
+}
+```
+
+## Style Properties
+
+| Property               | Type          | Description                                                         |
+| ---                    | ---           | ---                                                                 |
+| **Layout Mode**        |               |                                                                     |
+| `layout_mode`          | `LayoutType`  | Row vs. Column vs. Grid                                             |
+| `position_type`        | `Position`    | SelfDirected (absolute) vs. ParentDirected (in-flow) position       |
+| **Item size**          |               |                                                                     |
+| `size`                 | `Size<Units>` | The preferred height and width of item                              |
+| `min_size`             | `Size<Units>` | The minimum height and width of the item                            |
+| `max_size`             | `Size<Units>` | The maximum height and width of the item                            |
+| **Border**             |               |                                                                     |
+| `border`               | `Rect<Units>` | How large should the border be on each side?                        |
+| **Morphorm Container** |               |                                                                     |
+| `child_spacing`        | `Rect<Units>` | Sets the default "spacing" (~margin) on each side of child nodes    |
+| `row_between`          | `Units`       | Sets the default vertical "spacing" (~margin) between child nodes   |
+| `col_between`          | `Units`       | Sets the default horizontal "spacing" (~margin) between child nodes |
+| `grid_rows`            | `Vec<Units>`  | (Grid Container) Row definitions with a size for each row           |
+| `grid_cols`            | `Vec<Units>`  | (Grid Container) Column definitions with a size for each column     |
+| **Morphorm Item**      |               |                                                                     |
+| `spacing`              | `Rect<Units>` | The preferred spacing on each side of the item                      |
+| `min_spacing`          | `Rect<Units>` | The minimum spacing on each side of the item                        |
+| `max_spacing`          | `Rect<Units>` | The maximum spacing on each side of the item                        |
+| `row_index`            | `usize`       | (Grid Item) Zero-based index for the start row of the item          |
+| `col_index`            | `usize`       | (Grid Item) Zero-based index for the start column of the item       |
+| `row_span`             | `usize`       | (Grid Item) The number of rows the item spans                       |
+| `col_span`             | `usize`       | (Grid Item) The number of columns the item spans                    |
+
+### Analysis
+
+Nearly everything in Morphorm is simplified version of either Flexbox or CSS Grid. There are really three things that aren't:
+
+- The `child_spacing` and `*_between` properties. CSS does not allow you to specify child margins on the parent like this. It does have the `align-items` and `justify-items` properties, but those are not as powerful.
+- The `min_spacing` and `max_spacing` properties. CSS does not allow you to specify min or max values for margins.
+- The `Stretch` variant of `Units`. Flexbox/CSS Grid do not allow you to express "fill available space" as a size like this. To achieve this with Flexbox/CSS Grid you need to use special properties that are specified separately.
+
+The only really tricky thing here is the `width`/`height` properties. They are common to all algorithms, and furthermore by *both* parent and child nodes access this property. This means that the type of these properties really needs to be a single unified type. I thought this might be a blocker, however I have discovered that an upcoming CSS standard ([[css-sizing-4](https://www.w3.org/TR/css-sizing-4)]) actually does [define this functionality](https://www.w3.org/TR/css-sizing-4/#stretch-fit-sizing)) and in fact even calls it `stretch`. The CSS version doesn't have the weighting parameter (although I have [opened an issue](https://github.com/w3c/csswg-drafts/issues/8267) proposing that it does - no idea if that's the right place to do that though) so it is roughly equivalent to `Stretch(1.0)`, but that would a pretty straightforward extension.