From 609a9a7a3014d8dc450f122cb69bed33f4e55ca5 Mon Sep 17 00:00:00 2001 From: Joe Vilches Date: Wed, 13 Mar 2024 10:19:30 -0700 Subject: [PATCH] Add containing block documentation (#1615) Summary: Pull Request resolved: https://github.com/facebook/yoga/pull/1615 tsia Reviewed By: yungsters Differential Revision: D54822992 fbshipit-source-id: b98cd32bb2a753ff7088533fda4b4e9d4ad5a6e4 --- .../docs/advanced/containing-block.md | 89 +++++++++++++++++++ website-next/docs/advanced/errata.md | 2 +- .../docs/advanced/external-layout-systems.md | 2 +- website-next/docs/advanced/pixel-grid.md | 2 +- .../docs/styling/min-max-width-height.mdx | 2 +- website-next/docs/styling/position.mdx | 6 +- website-next/docs/styling/width-height.mdx | 2 +- 7 files changed, 97 insertions(+), 8 deletions(-) create mode 100644 website-next/docs/advanced/containing-block.md diff --git a/website-next/docs/advanced/containing-block.md b/website-next/docs/advanced/containing-block.md new file mode 100644 index 00000000..538835d9 --- /dev/null +++ b/website-next/docs/advanced/containing-block.md @@ -0,0 +1,89 @@ +--- +sidebar_position: 2 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import Playground from '@site/src/components/Playground'; + +# Containing block + +Often times certain properties depend on a node beyond the +one it is applied to. An example of this is percentage lengths like `width: 50%` which +will set the width of a node to 50% of some other length. That other length is determined +by the size of the _containing block_. A containing block is not a Yoga-specific +concept and exists in the [web](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block), +but since Yoga only implements a subset of web browser capabilities the behavior of +containing blocks is much more streamlined and it is helpful to frame it differently. + +### Identifying the containing block of a node + +- If the [position type](/docs/styling/position) of a node is static or relative then the containing block + is always the _content box_ of the parent. This is because in Yoga every node is a + flex container and therefore establishes a formatting context which would form a + containing block on the web. The content box is formed by the node without margin, padding, or borders. +- If the [position type](/docs/styling/position) of a node is absolute then the containing block will be + the _padding box_ (the content box plus padding) of any of: + - The nearest non-static ancestor. + - The nearest ancestor which is configured to always form a containing block. This + is helpful for supporting things outside of Yoga which would form a containing block + on the web, such as [filters](https://developer.mozilla.org/en-US/docs/Web/CSS/filter) + or [transforms](https://developer.mozilla.org/en-US/docs/Web/CSS/transform). This + is done by calling the corresponding API for the lanuage you are working in. + + + ```cpp + YGNodeSetAlwaysFormsContainingBlock(node, true /*alwaysFormsContainingBlock*/); + ``` + + + ```java + node.setAlwaysFormsContainingBlock(true /*alwaysFormsContainingBlock*/); + ``` + + + ```typescript + node.setAlwaysFormsContainingBlock(true /*alwaysFormsContainingBlock*/); + ``` + + + - The root if none of the above apply. Note that this is different from the web + which has the notion of the _initial containing block_ that depends on the size + of the viewport. +- If the node in question is the root then there is no containing block, but it will + use the `availableWidth` and `availableHeight` that is passed in to the call to + [`CalculateLayout`](/docs/getting-started/laying-out-a-tree). + +### What the containing block affects + +- Any percentage-based lengths will depend on the size of the containing block. + Specifically the [height](/docs/styling/width-height), top, and bottom properties will use the height of the + containing block. The [width](/docs/styling/width-height), left, right, [margin](/docs/styling/margin-padding-border), + and [padding](/docs/styling/margin-padding-border) will use the width of the containing block. +- Any insets (left, right, top, bottom, etc.) applied to absolute nodes will be + relative to the corresponding edge of the containing block. + + + + + + + +`} /> diff --git a/website-next/docs/advanced/errata.md b/website-next/docs/advanced/errata.md index dbfe7f89..d88e371a 100644 --- a/website-next/docs/advanced/errata.md +++ b/website-next/docs/advanced/errata.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 5 --- # Errata and layout conformance diff --git a/website-next/docs/advanced/external-layout-systems.md b/website-next/docs/advanced/external-layout-systems.md index e36c9ced..f4f62aa2 100644 --- a/website-next/docs/advanced/external-layout-systems.md +++ b/website-next/docs/advanced/external-layout-systems.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 3 --- # Integrating with external layout systems diff --git a/website-next/docs/advanced/pixel-grid.md b/website-next/docs/advanced/pixel-grid.md index 6c9fd1b0..6a935561 100644 --- a/website-next/docs/advanced/pixel-grid.md +++ b/website-next/docs/advanced/pixel-grid.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 2 --- # Pixel grid alignment diff --git a/website-next/docs/styling/min-max-width-height.mdx b/website-next/docs/styling/min-max-width-height.mdx index f060d2f5..11cf0e0f 100644 --- a/website-next/docs/styling/min-max-width-height.mdx +++ b/website-next/docs/styling/min-max-width-height.mdx @@ -9,7 +9,7 @@ import Playground from '@site/src/components/Playground'; These properties set the maximum and minimum size constraints of a node. They have higher priority than all other properties and will always be respected. Constraints can be specified as either absolute pixel values or as percentages of their -[containing block's](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block) size. By default all these constraints are `undefined`. +[containing block's](/docs/advanced/containing-block) size. By default all these constraints are `undefined`.