diff --git a/doc/components.md b/doc/components.md index f5c7fadaf7..ab243c1fc1 100644 --- a/doc/components.md +++ b/doc/components.md @@ -1,6 +1,6 @@ # Components Reference -All components are imported from `@telefonica/mistica`. +All components are imported from `@telefonica/mistica`. Before using any component, you should **always** read the definition .d.ts files located in `node_modules` so you have all the props and JSDoc context. ```tsx import {ButtonPrimary, Stack, Text2, ...} from '@telefonica/mistica'; diff --git a/doc/layout.md b/doc/layout.md index d4cde15556..8e12609ffd 100644 --- a/doc/layout.md +++ b/doc/layout.md @@ -11,6 +11,7 @@ - [around](#around) - [evenly](#evenly) - [nesting](#nesting) + - [Grow](#grow) - [Align](#align) - [Grid / GridItem](#grid--griditem) - [NegativeBox](#negativebox) @@ -49,7 +50,7 @@ spacing. All padding props accept a numeric value or a responsive object `{mobil ```tsx - + Example ``` @@ -57,6 +58,14 @@ spacing. All padding props accept a numeric value or a responsive object `{mobil :warning: Do not use `Box` to add external spacings or distribute items, instead use `Stack` or `Inline`. +You can also use Box as a fixed width container: + +```tsx + + Example + +``` + ## Stack Vertically distributes its children using the given `space` separation. @@ -159,6 +168,41 @@ with a value on the right via `space="between"`: The outer `Inline` distributes the two groups to opposite ends; the inner `Inline` keeps the icon tightly grouped with its label at a fixed gap. +### Grow + +Use the `expand` prop to make one or more children of an `Inline` grow to fill the remaining horizontal space. +It takes the index (or an array of indexes) of the children that should grow. Indexes follow +`React.Children.toArray` order, so empty nodes (`null`, `false`) are skipped but rendered elements always +count. You don't wrap the growing child in anything — `Inline` already wraps every child in its own element: + +```tsx + + 4,6 + + 150 valoraciones + +``` + +```tsx + + + + + +``` + +**Common mistakes.** `Inline` wraps each child in its own element, so growing a child by wrapping it in a +`
` (or `flex-grow`) does nothing useful. Neither does `` — `Box` has +no `style` prop, so a flex or width passed that way is silently dropped and the row collapses or overflows its +container. Reach for `expand` (and `` for any fixed sibling) instead. + ## Align Positions its children within a container using CSS grid alignment. Useful for centering content or placing it diff --git a/doc/patterns.md b/doc/patterns.md index 97e5aeaa88..9c436fd249 100644 --- a/doc/patterns.md +++ b/doc/patterns.md @@ -97,6 +97,29 @@ Follow the 24/32/16 rule: ``` +### DO: Fill remaining horizontal space with `Inline` `expand` + +To make a row child grow into the leftover width next to a fixed-width sibling, use `Inline`'s `expand` prop +with the index/indexes of the children that should grow. Indexes follow `React.Children.toArray` order. + +```tsx +// ProgressBar fills remaining space + + + + +``` + +### DON'T: grow children with raw flex or `style` on `Box` + +```tsx +// ❌ raw flexbox div — breaks; Inline already wraps each child in a div +
+
...
+
...
+
+``` + ## Color dos and don'ts ### DO: Use design tokens