diff --git a/CHANGELOG.md b/CHANGELOG.md
index 76f99e9a22..4fec99b9a1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,7 +20,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
### BREAKING CHANGES
- Use regular components instead of `Label` in `RadioGroupItem` @layershifter ([#1070](https://github.com/stardust-ui/react/pull/1070))
- Remove `Flex.Gap` component, and convert the `gap` styles to `margins` on the child elements of the `Flex` component @mnajdova ([#1074](https://github.com/stardust-ui/react/pull/1074))
-- Dropdown: control highlightedIndex from Dropdown @silviuavram ([#966](https://github.com/stardust-ui/react/pull/966))
+- `Dropdown`: control highlightedIndex from `Dropdown` @silviuavram ([#966](https://github.com/stardust-ui/react/pull/966))
### Fixes
- Add aria posinset and setsize, hide menu indicator from narration @jurokapsiar ([#1066](https://github.com/stardust-ui/react/pull/1066))
@@ -36,6 +36,9 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
- Add `placeholderColor` variable for `Input` component in Teams theme @layershifter ([#1092](https://github.com/stardust-ui/react/pull/1092))
- Add and export files icons in Teams theme @codepretty ([#1094](https://github.com/stardust-ui/react/pull/1094))
+### Documentation
+- Add layout guide @kuzhelov ([#1091](https://github.com/stardust-ui/react/pull/1091))
+
## [v0.23.1](https://github.com/stardust-ui/react/tree/v0.23.1) (2019-03-13)
[Compare changes](https://github.com/stardust-ui/react/compare/v0.23.0...v0.23.1)
diff --git a/docs/src/components/GuidesNavigationFooter.tsx b/docs/src/components/GuidesNavigationFooter.tsx
new file mode 100644
index 0000000000..7892ef23ae
--- /dev/null
+++ b/docs/src/components/GuidesNavigationFooter.tsx
@@ -0,0 +1,45 @@
+import * as React from 'react'
+import { Link } from 'react-router-dom'
+import { Button, Flex, Divider } from '@stardust-ui/react'
+
+type PageDescriptor = {
+ name: string
+ url: string
+}
+
+type GuidesNavigationFooterProps = {
+ previous?: PageDescriptor
+ next?: PageDescriptor
+}
+
+const GuidesNavigationFooter: React.FC
- For layouts and positioning please prefer Flex and{' '}
- Grid components, we also have{' '}
- Text component to wrap text. In other cases please try to
- use existing components and apply styles via theming features. You also can{' '}
- create your own custom component for custom
- behaviors.
-
- Remember that
+ Get more information on Stardust's approach to layout from{' '}
+ Layout guide.
+
+ Get more information on Stardust's approach to layout from{' '}
+ Layout guide.
+
+
+
+ Box component should be used carefully, in almost all cases you don't need it.
+
styles that applied directly to any component are not friendly
- for theme switching, prefer to use variables instead of styles for
- overrides.
+ Remember that styles prop applied directly to an element most probably will
+ break theme switching scenarios - thus, prefer to use variables instead of{' '}
+ styles for overrides.
Segment component shouldn't be used to handle layout aspects. To address
+ layouts and positioning aspects refer to Flex and{' '}
+ Grid components (and general{' '}
+ Layout guide).
+ {content}
@@ -522,23 +522,9 @@ export default () => (
'https://github.com/stardust-ui/accessibility/blob/master/CONTRIBUTING.md',
)}
-
-
-
)
diff --git a/docs/src/views/IntegrateCustomComponents.tsx b/docs/src/views/IntegrateCustomComponents.tsx
index b68e2d549d..654e8a3173 100644
--- a/docs/src/views/IntegrateCustomComponents.tsx
+++ b/docs/src/views/IntegrateCustomComponents.tsx
@@ -1,8 +1,6 @@
import * as React from 'react'
import { NavLink } from 'react-router-dom'
import {
- Button,
- Divider,
Header,
Provider,
createComponent,
@@ -13,6 +11,7 @@ import {
import DocPage from '../components/DocPage/DocPage'
import ExampleSnippet from '../components/ExampleSnippet/ExampleSnippet'
import { ReactChildren } from 'src/types'
+import GuidesNavigationFooter from '../components/GuidesNavigationFooter'
interface StyledButtonProps {
className?: string
@@ -276,16 +275,6 @@ export default () => (
{value}
+
+const link = (content, href, isExternal = false) => (
+
+ {content} {isExternal ? The following components are introduced by Stardust to handle layout aspects:
++ Sometimes it might not be evident if some particular case is a case of 1D (i.e. {code('Flex')} + ) or 2D (i.e. {code('Grid')}) layout. As a result, quite often {code('Grid')} component is + used at places where it is sufficient to use {code('Flex')}. +
+Here is the question you might ask yourself to decide on that:
++ {links.segment} and {links.box} components may be abused for layout purposes, like in the + following examples: +
++ While it might seem that the intent is addressed with the approach taken, however, this is + wrong for the following reason: +
++ Stardust makes it very important to{' '} + follow component's semantics at the first place, and only then consider the + visual aspects. ++
If we'd refer to the semantics provided in the description for {links.segment} component:
+A segment is used to create a grouping of related content.+
+ This description suggests that purpose of {code('Segment')} is not a layout. Thus, this + component shouldn't be used for layout purposes, as this will break component's semantics - + and, as a consequence, it might break accessibility and theming, as those both adhere to + component's semantics at the first place. +
+Same conclusions applies to the {links.box} component.
++ Use {code('Flex.Item')} component to wrap child elements only in case if their flex styles + should be overriden. ++
+ There is no strict need to use {code('Flex.Item')} component as a direct child of{' '} + {code('Flex')} - one may use {code('Flex.Item')} component only when it is necessary to tweak + flex styles of individual child item. +
+As a consequence of this:
++ Each {code('Flex.Item')} element being introduced without any props specified should be + considered for removal. ++
+ Flex component was designed being able to address all flexbox layout scenarios with minimal + amount of DOM elements rendered. In addition, there are props to address most common{' '} + {link( + 'flexbox usage scenarios', + 'https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flexible_Box_Layout/Typical_Use_Cases_of_Flexbox', + true, + )}{' '} + (e.g. {code('push')} prop) - the value of these props is that they introduce the least amount + of DOM elements necessary to accomplish corresponding use-case. +
++ Let's consider one of the most representative examples - a navigation menu. Suppose that we + want a menu bar with logo on the left side and set of nav links on the right. +
++ Quite often this is achieved by introducing a top-level flex container with two children: + first is a logo, and the second one is another container ({code('Flex')}, renders to{' '} + {code('
')}) with a group of buttons: + ++ It turns out that this approach introduces unnecessary nesting level - it is possible to + achieve the same goal by using just top-level container, with no buttons container: +
++ Note that{' '} + {code('Flex.Item')} doesn't result in any additional DOM element rendered - + its sole purpose is just to pass style props to its child. +
++ Consider to review set of examples on the {links.flex} page - as there might be an example + that suits your needs.{' '} + Each of these examples is optimized in terms of DOM elements rendered. ++
Variables are defined at two levels, the site level and the component level.
-
Site variables define your site, app, or business. These are global values, like brand colors
and typography, that are shared across many components.
@@ -75,7 +76,7 @@ export default () => (
)}
/>
-
Component variables define theme values for a specific component. This includes information
such as colors, borders, or box model values.
@@ -299,24 +300,9 @@ export default () => (
structure of the animation property in any of the Stardust components.