Semantic delta · 1
docs/src/components/docs.js
diff --git a/docs/src/components/docs.css b/docs/src/components/docs.css
index 497a31980..03798554f 100644
--- a/docs/src/components/docs.css
+++ b/docs/src/components/docs.css
@@ -26,6 +26,108 @@
section.mdx-content .section-inner {
padding: 0px 100px 75px 100px;
+ max-width: 1000px;
+}
+
+section.docs-header .section-inner {
+ max-width: 1000px;
+}
+
+section.mdx-content .section-inner {
+ padding: 0px 100px 75px 100px;
+ max-width: 1000px;
+}
+
+section.docs-header p a {
+ color: var(--color-accent)
+}
+
+section.mdx-content p a {
+ color: var(--color-accent)
+}
+
+.mdx-content hr {
+ border: 0;
+ height: 1px;
+ background: #ccc;
+ margin-bottom: 40px;
+}
+
+.docs-header p {
+ line-height: 180%;
+}
+
+.mdx-content p {
+ line-height: 180%;
+}
+
+.mdx-content p + ul {
+ margin-top: -10px;
+}
+
+.mdx-content li {
+ list-style: none;
+ line-height: 180%;
+}
+
+.mdx-content li + li {
+ margin-top: 10px;
+}
+
+.mdx-content li:before {
+ content: '-';
+ margin-left: -20px;
+ margin-right: 10px;
+}
+
+.mdx-content li code, .mdx-content p code {
+ color: var(--color-accent);
+}
+
+.mdx-content li code::before, .mdx-content p code::before {
+ content: '`';
+}
+
+.mdx-content li code::after, .mdx-content p code::after {
+ content: '`';
+}
+
+.code-block {
+ display: flex;
+ flex-direction: column;
+ background-color: rgb(41, 44, 51);
+ color: var(--color-dark);
+ box-shadow: 0 0 6px 0 var(--color-shadow);
+ border-radius: 10px;
+ overflow: hidden;
+ margin-bottom: 50px;
+}
+
+.code-block .code-wrapper {
+ display: flex;
+ flex-direction: column;
+ background-color: rgb(41, 44, 51);
+ color: var(--color-dark);
+ box-shadow: 0 0 6px 0 var(--color-shadow);
+ border-radius: 10px;
+ overflow: hidden;
+ padding: 10px;
+}
+
+.code-block pre {
+ margin: 0px;
+ border-radius: 0px;
+ font-size: 14px;
+}
+
+.code-block > code {
+ background-color: rgb(41, 44, 51);
+ padding: 10px;
+ padding-left: 18px;
+ font-size: 14px;
+ font-weight: bold;
+ border-bottom: 1px solid #666;
+ color: white;
}
@media (max-width: 850px) {
diff --git a/docs/src/components/docs.js b/docs/src/components/docs.js
index 7d688d17b..201b91395 100644
--- a/docs/src/components/docs.js
+++ b/docs/src/components/docs.js
@@ -6,15 +6,22 @@ import Layout from "../components/layout"
import SEO from "../components/seo"
import './docs.css'
+import SyntaxHighlighter from 'react-syntax-highlighter';
+import { atomOneDark } from 'react-syntax-highlighter/dist/esm/styles/hljs';
+
export default ({children, location}) => (
<MDXProvider>
<Layout>
<SEO title="Stretch" keywords={[`rust`, `android`, `ios`, `web`, `flexbox`]} />
- <section>
+ <section className="docs-header">
<div className="section-inner">
- <h2>Documentation</h2>
+ <h1>Documentation</h1>
<p>
Stretch is available for Rust, Kotlin, Swift, and JavaScript. We will be adding more language bindings over time.
+ For general help on using flexbox we suggest
+ reading <a href="https://css-tricks.com/snippets/css/a-guide-to-flexbox/">css-tricks.com/snippets/css/a-guide-to-flexbox</a> and
+ playing around with <a href="https://flexboxfroggy.com">flexboxfroggy.com</a>. Or you can always read the spec itself
+ at <a href="https://www.w3.org/TR/css-flexbox-1/">www.w3.org/TR/css-flexbox-1</a>
</p>
<div className="doc-pills">
<Link to="/docs/rust" className={`doc-pill ${location.pathname.endsWith("rust") ? "active" : ""}`}>Rust</Link>
@@ -26,9 +33,22 @@ export default ({children, location}) => (
</section>
<section className="mdx-content">
<div className="section-inner">
- {children}
+ <div>
+ {children}
+ </div>
</div>
</section>
</Layout>
</MDXProvider>
-);
\ No newline at end of file
+);
+
+export function Code({file, lang, children}) {
+ return (
+ <div className="code-block">
+ { file && <code>{file}</code> }
+ <div className="code-wrapper">
+ <SyntaxHighlighter language={lang} style={atomOneDark}>{children.trim()}</SyntaxHighlighter>
+ </div>
+ </div>
+ );
+}
\ No newline at end of file
diff --git a/docs/src/components/layout.css b/docs/src/components/layout.css
index 6a62be161..019fab588 100644
--- a/docs/src/components/layout.css
+++ b/docs/src/components/layout.css
@@ -182,7 +182,7 @@ textarea {
flex-direction: column;
}
- .section-inner h2 {
+ .section-inner > h2 {
margin-top: 8%;
margin-bottom: 5%;
}
diff --git a/docs/src/pages/docs/rust.mdx b/docs/src/pages/docs/rust.mdx
index 0b33ce79b..34dfeb589 100644
--- a/docs/src/pages/docs/rust.mdx
+++ b/docs/src/pages/docs/rust.mdx
@@ -1,6 +1,436 @@
-import Layout from '../../components/docs.js';
+import Layout, { Code } from '../../components/docs.js';
export default Layout;
-# HEllo!
+# Installation
+Let's start by create a new project with `cargo new hello_stretch --bin`. Before we can write any code we have to add Stretch as a dependency in `Cargo.toml`.
+
+<Code lang="toml" file="Cargo.toml">{`
+[dependencies]
+stretch = "0.2.2"
+`}</Code>
+
+We are ready to use Stretch! Open up `hello_stretch/src/main.rs` and replace its contents with the following. Once finished you should be able to run `cargo run` to see the results of this basic layout calculation.
+
+<Code lang="rust" file="main.rs">{`
+use stretch::{style::*, node::Node, geometry::Size};
+
+fn main() {
+ let node = Node::new(Style {
+ size: Size {
+ width: Dimension::Points(100.0),
+ height: Dimension::Points(100.0),
+ },
+ ..Default::default()
+ }, vec![]);
+
+ let layout = node.compute_layout(Size::undefined());
+ dbg!(layout);
+}
+`}</Code>
+
+# Basics
+`Node`s are the core building blocks of a stretch layout tree. A node needs a `Style` which describes the `flexbox` properties for the node. By adding nodes as children to a parent node we create a tree which we can perform layout on. The result of a layout computation is a tree of `Layout` nodes. This tree matches the structure of the `Node` tree but contains the computed layout of each node.
+
+<Code lang="rust" file="main.rs">{`
+use stretch::{style::*, node::Node, geometry::Size};
+
+fn main() {
+ let node = Node::new(Style { ..Default::default() }, vec![
+ Node::new(Style {
+ size: Size {
+ width: Dimension::Points(100.0),
+ height: Dimension::Points(100.0),
+ },
+ ..Default::default()
+ })
+ ]);
+
+ let layout = node.compute_layout(Size::undefined()).unwrap();
+
+ layout.width; // 100.0
+ layout.height; // 100.0
+ layout.children.len(); // 1
+}
+`}</Code>
+
+Nodes can be be mutated and stretch will automatically recompute only the subtrees which have changed. This is incredibly powerfull if you have a large node tree, perhaps representing the UI of an app, and only need to change the height of a single element.
+
+<Code lang="rust" file="main.rs">{`
+use stretch::{style::*, node::Node, geometry::Size};
+
+fn main() {
+ let mut node = Node::new(Style { ..Default::default() }, vec![
+ Node::new(Style {
+ size: Size {
+ width: Dimension::Points(100.0),
+ height: Dimension::Points(100.0),
+ },
+ ..Default::default()
+ })
+ ]);
+
+ node.compute_layout(Size::undefined());
+
+ // Mutate node
+ node.set_style(Style {
+ size: Size {
+ width: Dimension::Points(100.0),
+ height: Dimension::Points(100.0),
+ },
+ ..Default::default()
+ });
+
+ // This call will return partially cached results
+ node.compute_layout(Size::undefined());
+}
+`}</Code>
+
+# Node
+Create a new node with children (or an empty list). Children can be removed or added later on as well.
+
+<Code lang="rust">{`Node::new(style: Style, children: Vec<&Node>) -> Node`}</Code>
+
+----
+
+Create a new leaf node. This is a node without children which knows how to measure its own intrinsic size. Examples of common leaf nodes are images and text.
+
+<Code lang="rust">{`Node::new_leaf(style: Style, measure: MeasureFunc) -> Node`}</Code>
+
+----
+
+Set the measure function on a node. This function will be called on leaf nodes to resolve the instrinsic size of the node given a set of constraints.
+
+<Code lang="rust">{`Node::set_measure(&mut self, measure: Option<MeasureFunc>)`}</Code>
+
+----
+
+Adds a child to an existing node.
+
+<Code lang="rust">{`Node::add_child(&mut self, child: &Node)`}</Code>
+
+----
+
+Replaces the children of an existing node.
+
+<Code lang="rust">{`Node::set_children(&mut self, children: Vec<&Node>)`}</Code>
+
+----
+
+Removes a previously added child from an existing node.
+
+<Code lang="rust">{`Node::remove_child(&mut self, child: &Node) -> Node`}</Code>
+
+----
+
+Removes the child at the given index of an existing node.
+
+<Code lang="rust">{`Node::remove_child_at_index(&mut self, index: usize) -> Node`}</Code>
+
+----
+
+Replaces the child at the given index of an existing node with the given new child.
+
+<Code lang="rust">{`Node::replace_child_at_index(&mut self, index: usize, child: &Node) -> Node`}</Code>
+
+----
+
+Returns the list of children owned by this node.
+
+<Code lang="rust">{`Node::children(&self) -> Vec<Node>`}</Code>
+
+----
+
+Returns the number of children associated with this node.
+
+<Code lang="rust">{`Node::child_count(&self) -> usize`}</Code>
+
+----
+
+Updates the style of an existing node.
+
+<Code lang="rust">{`Node::set_style(&mut self, style: Style)`}</Code>
+
+----
+
+Returns the current style of a node.
+
+<Code lang="rust">{`Node::style(&self) -> Style`}</Code>
+
+----
+
+Marks the node as dirty and propagates this up the node tree. This function is called internally for any mutating function. The only time you have to ensure to call it manually is if some application state has changed which will effect the intrinsic size of a leaf node. For example if the text of a text node has changed.
+
+<Code lang="rust">{`Node::mark_dirty(&mut self)`}</Code>
+
+----
+
+Returns wether of not this node is marked as dirty and will need to be recalculated during the next layout pass.
+
+<Code lang="rust">{`Node::dirty(&self) -> bool`}</Code>
+
+----
+
+Computes the layout of a node tree given a size. The size passed in is used to compute percentage sizes on the root node. If you don't need to do this then it is fine to pass `Size::undefined()` however you will typically pass in the size of the viewport which will host this computed layout. The resulting tree of `Layout` nodes mimics the structure of the computed `Node` tree and includes position and size information. `Number` is defined in `stretch::number::Number` and is an abstraction which closely mimics `Option<f32>`.
+
+<Code lang="rust">{`Node::compute_layout(&self, size: Size<Number>) -> Result<Layout>`}</Code>
+
+# Style
+The `Style` struct contains all the properties associated with flexbox as well as some properties which we found useful outside of flexbox. For example `position_type` can be set to `PositionType::Absolute` which puts the node into a absolute layout context instead of a flexbox context. `aspect_ratio` is another property not part of the flexbox specification which when set ensures the node matches a certain aspect ratio.
+
+<Code lang="rust">{`
+struct Style {
+ pub display: Display,
+ pub position_type: PositionType,
+ pub direction: Direction,
+ pub flex_direction: FlexDirection,
+ pub flex_wrap: FlexWrap,
+ pub overflow: Overflow,
+ pub align_items: AlignItems,
+ pub align_self: AlignSelf,
+ pub align_content: AlignContent,
+ pub justify_content: JustifyContent,
+ pub position: Rect<Dimension>,
+ pub margin: Rect<Dimension>,
+ pub padding: Rect<Dimension>,
+ pub border: Rect<Dimension>,
+ pub flex_grow: f32,
+ pub flex_shrink: f32,
+ pub flex_basis: Dimension,
+ pub size: Size<Dimension>,
+ pub min_size: Size<Dimension>,
+ pub max_size: Size<Dimension>,
+ pub aspect_ratio: Number,
+}
+`}</Code>
+
+----
+
+`AlignItems` describes how to align children along the cross axis of their parent. `AlignItems` is very similar to `JustifyContent` but instead of applying to the main axis, `AlignItems` applies to the cross axis.
+
+- `FlexStart` aligns children of a container to the start of the container's cross axis.
+- `FlexEnd` aligns children of a container to the end of the container's cross axis.
+- `Center` aligns children of a container in the center of the container's cross axis.
+- `Baseline` aligns children of a container to the baseline of that container's cross axis.
+- `Stretch` stretches children of a container to match the height of the container's cross axis.
+
+Optional, if left undefined `Stretch` is the default value.
+
+<Code lang="rust">{`
+enum AlignItems {
+ FlexStart,
+ FlexEnd,
+ Center,
+ Baseline,
+ Stretch,
+}
+`}</Code>
+
+----
+
+`AlignSelf` has the same options and effect as setting `AlignItems` on the containing node but instead of affecting the children within the node you can apply this property to a single child to change its alignment within its parent. `AlignSelf` overrides any option set on the parent with `AlignItems`.
+
+- `Auto` delegates to the parent's `AlignItems` property.
+- `FlexStart` aligns children of a container to the start of the container's cross axis.
+- `FlexEnd` aligns children of a container to the end of the container's cross axis.
+- `Center` aligns children of a container in the center of the container's cross axis.
+- `Baseline` aligns children of a container to the baseline of that container's cross axis.
+- `Stretch` stretches children of a container to match the height of the container's cross axis.
+
+Optional, if left undefined `Auto` is the default value.
+
+<Code lang="rust">{`
+enum AlignSelf {
+ Auto,
+ FlexStart,
+ FlexEnd,
+ Center,
+ Baseline,
+ Stretch,
+}
+`}</Code>
+
+----
+
+`AlignContent` defines the distribution of lines along the cross-axis. This only has effect when items are wrapped to multiple lines using `FlexWrap`.
+
+- `FlexStart` aligns wrapped lines to the start of the container's cross axis.
+- `FlexEnd` aligns wrapped lines to the end of the container's cross axis.
+- `Center` aligns wrapped lines in the center of the container's cross axis.
+- `Stretch` stretches wrapped lines to match the height of the container's cross axis.
+- `SpaceBetween` evenly spaces wrapped lines across the container's main axis, distributing remaining space between the lines.
+- `SpaceAround` evenly spaces wrapped lines across the container's main axis, distributing remaining space around the lines. Compared to space between using space around will result in space being distributed to the begining of the first lines and end of the last line.
+
+Optional, if left undefined `Stretch` is the default value.
+
+<Code lang="rust">{`
+enum AlignContent {
+ FlexStart,
+ FlexEnd,
+ Center,
+ Stretch,
+ SpaceBetween,
+ SpaceAround,
+}
+`}</Code>
+
+----
+
+The `Direction` property specifies wether the component should be laid out in `LTR` or `RTL` writing mode.
+
+Optional, `Inherit` by default (root node will implicitly default to `LTR`).
+
+<Code lang="rust">{`
+enum Direction {
+ Inherit,
+ LTR,
+ RTL,
+}
+`}</Code>
+
+----
+
+The `Display` property specifies wether the component should be laid out as `Flex` or not at all. If `None` is specified then the node will have a resulting size of zero. In the future this enum will be expanded to include more display options such as `Grid`.
+
+Optional, `Flex` by default.
+
+<Code lang="rust">{`
+enum Display {
+ Flex,
+ None,
+}
+`}</Code>
+
+----
+
+`FlexDirection` controls the direction in which children of a node are laid out. This is also referred to as the main axis. The main axis is the direction in which children are laid out. The cross axis the the axis perpendicular to the main axis, or the axis which wrapping lines are laid out in.
+
+- `Row` aligns children from left to right. If wrapping is enabled then the next line will start under the first item on the left of the container.
+- `Column` aligns children from top to bottom. If wrapping is enabled then the next line will start to the left first item on the top of the container.
+- `RowReverse` aligns children from right to left. If wrapping is enabled then the next line will start under the first item on the right of the container.
+- `ColumnReverse` aligns children from bottom to top. If wrapping is enabled then the next line will start to the left first item on the bottom of the container.
+
+Optional, if left undefined `Row` is the default value.
+
+<Code lang="rust">{`
+enum FlexDirection {
+ Row,
+ Column,
+ RowReverse,
+ ColumnReverse,
+}
+`}</Code>
+
+----
+
+`JustifyContent` describes how to align children within the main axis of their container. For example, you can use this property to center a child horizontally within a container with `FlexDirection` set to `FlexDirection::Row` or vertically within a container with `FlexDirection` set to `FlexDirection::Column`.
+
+- `FlexStart` aligns children of a container to the start of the container's main axis.
+- `FlexEnd` aligns children of a container to the end of the container's main axis.
+- `Center` aligns children of a container in the center of the container's main axis.
+- `SpaceBetween` evenly spaces of children across the container's main axis, distributing remaining space between the children.
+- `SpaceAround` evenly spaces of children across the container's main axis, distributing remaining space around the children. Compared to space between using `spaceAround` will result in space being distributed to the beginning of the first child and end of the last child.
+- `SpaceEvenly` evenly spaces of children across the container's main axis, distributing remaining space around the children so that visually there is equal space around every child including at the edges.
+
+Optional, if left undefined `FlexStart` is the default value.
+
+<Code lang="rust">{`
+enum JustifyContent {
+ FlexStart,
+ FlexEnd,
+ Center,
+ SpaceBetween,
+ SpaceAround,
+ SpaceEvenly,
+}
+`}</Code>
+
+----
+
+The `Overflow` property specifies how the node should handle children which overflow their parent's size. This property is currently not used but may be used in the future.
+
+Optional, `Visible` by default.
+
+<Code lang="rust">{`
+enum Overflow {
+ Visible,
+ Hidden,
+ Scroll,
+}
+`}</Code>
+
+----
+
+The `PositionType` property specifies wether the component should be laid out relative to its sibling or absolutely positioned within its parent.
+
+Optional, `Relative` by default.
+
+<Code lang="rust">{`
+enum PositionType {
+ Relative,
+ Absolute,
+}
+`}</Code>
+
+----
+
+The `FlexWrap` property controls what happens when children overflow the size of the container along the main axis. By default children are forced into a single line (which can shrink components).
+
+- `Wrap` enables wrapping of children if they overflow the main axis of the container.
+- 'NoWrap' disables wrapping of children, children will instead shrink to fit the main axis or overflow depending on their `flex_shrink` setting.
+- `WrapReverse` enables wrapping of children if they overflow the main axis of the container. Unlike `Wrap`, lines are laid out in reverse order.
+
+Optional, if left undefined `NoWrap` is the default value.
+
+<Code lang="rust">{`
+enum FlexWrap {
+ NoWrap,
+ Wrap,
+ WrapReverse,
+}
+`}</Code>
+
+
+# Layout
+`Layout` nodes are returned from a layout calculation and mimic the structure of the computed `Node` tree.
+
+<Code lang="rust">{`
+struct Layout {
+ pub size: Size<f32>,
+ pub location: Point<f32>,
+ pub children: Vec<Layout>,
+}
+`}</Code>
+
+# Number
+`Number` closely mimics `Option<f32>`. We needed to implement our own optional type to be able to implement certain traits not found on the built in optional.
+
+
+<Code lang="rust">{`
+enum Number {
+ Defined(f32),
+ Undefined,
+}
+`}</Code>
+
+# Geometry
+The geometry module in stretch defines some basic geometric data types used throughout the API as well as internally in the library. This includes `Rect`, `Size`, and `Point`. They are fairly self explanatory except for `Rect` perhaps. Insteaf of the typical `left`, `top`, `right`, `bottom` fields you may expect the `Rect` struct in stretch opts for using `start` and `end` instead of `left` and `right`. This enables stretch to force users of its API to be accessible for RTL users.
+
+<Code lang="rust">{`
+struct Rect<T> {
+ pub start: T,
+ pub end: T,
+ pub top: T,
+ pub bottom: T,
+}
+
+struct Size<T> {
+ pub width: T,
+ pub height: T,
+}
+
+struct Point<T> {
+ pub x: T,
+ pub y: T,
+}
+`}</Code>
-This is the rust docs yo.
\ No newline at end of file