fix(docs): (stacks) Updates from doc review

markdown/dev/guides/designs/stacks/en.md

@@ -5,8 +5,8 @@ order: 110
 
 [Stacks](/reference/api/stack) come into play when laying out a pattern.
 The FreeSewing core library, by default, will handle the layout of a pattern
-for you by placing all parts next to each other in as small a space as
+for you by placing all parts into stacks and arranging the stacks in as
-possible.
+small a space as possible.
 
 That is _typically_ what you want, but not always. For example, when sampling
 you want parts to be stacked on top of each other:
@@ -44,7 +44,9 @@ Under the hood, sampling uses multiple sets of settings and then uses stacks
 to place them on top of each other.  But this functionality is also available
 to patterns designers who want to use it.
 
-Essentially, stacks behave as layers. Parts that are on the same _stack_ will be stacked on top of each other in the layout.
+Essentially, a stack is a collection of parts.
+Parts in a stack act as layers, and they will be stacked directly on top
+of each other.
 
 You can stack parts from the same set, or from different sets.
 
@@ -52,9 +54,10 @@ You can stack parts from the same set, or from different sets.
 
 <Note>
 
-In the vast majority of cases you won't be using any stacks, or the stacking
+In the vast majority of cases, stacks will be handled for you by the
-will be handled for you by the core library (like in the sampling example
+core library (like in the sampling example above).
-above).
+By default, parts are added to a stack with the same name as the part,
+so you only need to specify a stack if you want a different behavior.
 
 </Note>
 

markdown/dev/reference/api/part/config/stack/en.md

@@ -32,10 +32,16 @@ This is because parts in the stack are drafted within the same stack
 space.
 
 Otherwise, if the `stack` property is not present, the default behavior
-is to assign the part to its own stack.
+is to use the part's name as its stack name.
-The part will not overlap other parts in drafting and printing layouts.
+
-This is because it is the only part drafted within its stack and
+- In a draft with only one set, this will result in each part having its
-because stacks do not overlap other stacks.
+own stack.
+With a default layout, the part will not overlap other parts because it is
+the only part drafted within its stack and stacks do not overlap.
+
+- In a draft with multiple sets, this will result in parts of the same name
+using the same stack.
+This is how we achieve the layered look of parts in sample drafts.
 
 <Related>
 

markdown/dev/reference/api/stack/asProps/en.md

@@ -10,3 +10,17 @@ The `Stack.asProps()` method returns a stack object suitable for renderprops.
 ```js
 Object stack.asProps()
 ```
+
+## Stack.asProps() returned object
+
+The `Stack.asProps()` method returns an object with the following properties:
+
+| Property | Description |
+| --------:| ----------- |
+| `attributes` | An `Attributes` instance holding the stack's attributes |
+| `bottomRight` | A `Point` that is the bottom right of the stack's bounding box |
+| `height` | Height of the bounding box of the stack in `mm` |
+| `name` | The name of the stack |
+| `parts` | An `Array` of the `Part`s in the stack |
+| `topLeft` | A `Point` that is the top left of the stack's bounding box |
+| `width` | Width of the bounding box of the stack in `mm` |

markdown/dev/reference/api/stack/en.md

@@ -2,13 +2,13 @@
 title: Stack
 ---
 
-A Stack object represents a layer within a pattern, holding one or
+A Stack object represents a collection of parts within a pattern.
-more parts..
+Stacks are used when laying out the pattern.
 
 <Related>
 
 See [Stacks](/guides/patterns/stacks)
-for information about how stacks are used in a pattern
+for information about how stacks are used in a pattern.
 
 </Related>
 
@@ -25,7 +25,7 @@ of the stack.
 
 Stack objects come with the following properties:
 
-- `attributes` : An [Attributes](/reference/api/attributes) instance holding the point's attributes
+- `attributes` : An [Attributes](/reference/api/attributes) instance holding the stack's attributes
 - `parts` : A set of parts in the stack
 - `name` : The name of the stack
 - `topleft` : A [Point](/reference/api/point) that is the top left of the stack's bounding box

markdown/dev/reference/api/stack/generateTransform/en.md

@@ -2,7 +2,7 @@
 title: Stack.generateTransform()
 ---
 
-The `Stack.generateTransform()` method generates transforms for the stack,
+The `Stack.generateTransform()` method generates SVG transforms for the stack,
 sets them as attributes, and returns the original stack.
 
 

markdown/dev/reference/api/stack/home/en.md

@@ -2,7 +2,8 @@
 title: Stack.home()
 ---
 
-The `Stack.home()` method calculates the stack's bounding box, sets it,
+The `Stack.home()` method calculates the stack's bounding box,
+setting the `width`, `height`, `topLeft`, and `bottomRight` properties,
 and returns the original stack.
 
 ## Stack.home() signature
@@ -15,3 +16,7 @@ Stack stack.home()
 ## Notes
 
 The bounding box is calculated taking into consideration the `margin` setting.
+
+`Stack.home()` caches its calculations by checking whether the stack's
+`topLeft` property has been set.
+If `topLeft` has a truthy value, it will not re-calculate.