Skip to content

Commit 5ba711c

Browse files
didoodidoo
committed
first draft doumentation for Flex and Flex::Item (mainly around the “Component API” section)
1 parent ca4ce22 commit 5ba711c

File tree

5 files changed

+118
-0
lines changed

5 files changed

+118
-0
lines changed

‎website/docs/layouts/flex/index.js

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
/**
2+
* Copyright (c) HashiCorp, Inc.
3+
* SPDX-License-Identifier: MPL-2.0
4+
*/
5+
6+
import Component from '@glimmer/component';
7+
8+
export default class Index extends Component {
9+
yourSidebarBooleanFlag = false;
10+
}

‎website/docs/layouts/flex/index.md

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
title: Layout::Flex
3+
description: A component used to implement layouts based on CSS flex
4+
caption: A layout-only component for the organization of content based on the CSS Flexbox model
5+
links:
6+
github: https://github.com/hashicorp/design-system/tree/main/packages/components/src/components/hds/layout/flex
7+
previewImage: assets/illustrations/layouts/flex.jpg
8+
navigation:
9+
keywords: ['layout', 'flex', 'flexbox']
10+
---
11+
12+
<section data-tab="Code">
13+
@include "partials/code/how-to-use.md"
14+
@include "partials/code/component-api.md"
15+
</section>
16+
17+
<section data-tab="Version history">
18+
@include "partials/version-history/version-history.md"
19+
</section>

‎website/docs/layouts/flex/partials/code/component-api.md

+75
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
## Component API
2+
3+
### Layout::Flex
4+
5+
<Doc::ComponentApi as |C|>
6+
<C.Property @name="tag" @type="string" @default="div">
7+
HTML tag to be used to render the flexbox element.
8+
</C.Property>
9+
<C.Property @name="direction" @type="enum" @values={{array "row" "column"}} @default="row">
10+
The value of the CSS `flex-direction` property, which sets how the flex items (children) are placed in the flex container, defining the [main axis](https://developer.mozilla.org/en-US/docs/Glossary/Main_Axis) and the direction (for a technical explanation: [see MDN reference](https://developer.mozilla.org/en-US/docs/Web/CSS/flex-direction)).
11+
<br/><br/>
12+
<em>Notice: we don't expose the "reverse" directions because they come with intrinsic accessibility limitations that we prefer our consumers to avoid.</em>
13+
</C.Property>
14+
<C.Property @name="justify" @type="enum" @values={{array "start" "center" "end" "space-between" "space-around" "space-evenly"}}>
15+
The value of the CSS `justift-content` property, which defines how the space is distributed between and around content items along the [main axis](https://developer.mozilla.org/en-US/docs/Glossary/Main_Axis) of the flex container (for a technical explanation: [see MDN reference](https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content)).
16+
<br/><br/>
17+
<em>Notice: we expose only a subset of the values allowed for this property, covering only the most common use cases.</em>
18+
<br/><br/>
19+
<em>Tip: when the `@direction` is `row` this argument controls the horizontal alignment; when it's `column` it controls the vertical alignment.</em>
20+
</C.Property>
21+
<C.Property @name="align" @type="enum" @values={{array "start" "center" "end" "stretch"}}>
22+
The value of the CSS `align-item` property, which controls the alignment of the flex items on the [cross axis](https://developer.mozilla.org/en-US/docs/Glossary/Cross_Axis) (for a technical explanation: [see MDN reference](https://developer.mozilla.org/en-US/docs/Web/CSS/align-items)).
23+
<br/><br/>
24+
<em>Notice: we expose only a subset of the values allowed for this property, covering only the most common use cases.</em>
25+
<br/><br/>
26+
<em>Tip: when the `@direction` is `row` this argument controls the vertical alignment; when it's `column` it controls the horizontal alignment.</em>
27+
</C.Property>
28+
<C.Property @name="wrap" @type="boolean" @default="false">
29+
If a `@wrap` parameter is provided, the flex items can wrap onto multiple lines when there is not enough space in the container to fit them all in a single line.
30+
</C.Property>
31+
<C.Property @name="isInline" @type="boolean" @default="false">
32+
If an `@isInline` parameter is provided, then the element will be displayed as `inline-flex` (useful to achieve specific layouts). Otherwise, it will have a `flex` layout.
33+
</C.Property>
34+
<C.Property @name="...attributes">
35+
This component supports use of [`...attributes`](https://guides.emberjs.com/release/in-depth-topics/patterns-for-components/#toc_attribute-ordering).
36+
</C.Property>
37+
</Doc::ComponentApi>
38+
39+
### Contextual components
40+
41+
#### [LF].Item
42+
43+
The `Layout::Flex::Item` component, yielded as contextual component, to be used as child of the `flexbox` element to control its `basis/grow/shrink` values (and other properties).
44+
45+
<Doc::ComponentApi as |C|>
46+
<C.Property @name="tag" @type="string" @default="div">
47+
HTML tag to be used to render the flex item element.
48+
</C.Property>
49+
<C.Property @name="basis" @type="string|0">
50+
The value (size) of the CSS `flex-basis` property, which sets the initial main size the flex item (for a technical explanation: [see MDN reference](https://developer.mozilla.org/en-US/docs/Web/CSS/flex-basis)).
51+
<br/><br/>
52+
<em>Notice: when the value is set to `0` a CSS class is used to apply the `flex-basis` property; in all the other cases an inline `style` declaration is used, to accomodate for all the possible values that this CSS property allows.</em>
53+
</C.Property>
54+
<C.Property @name="grow" @type="boolean|number|string">
55+
The value (size or keyword) of the CSS `flex-grow` property, which sets the flex grow factor of the flex item (for a technical explanation: [see MDN reference](https://developer.mozilla.org/en-US/docs/Web/CSS/flex-grow)).
56+
<br/><br/>
57+
<em>Notice: when the value is set to `true/false` or `0/1` a CSS class is used to apply the `flex-grow` property; in all the other cases an inline `style` declaration is used, to accomodate for all the possible values that this CSS property allows.</em>
58+
</C.Property>
59+
<C.Property @name="shrink" @type="boolean|number|string">
60+
The value (size or keyword) of the CSS `flex-shrink` property, which sets sets the flex shrink factor of the flex item (for a technical explanation: [see MDN reference](https://developer.mozilla.org/en-US/docs/Web/CSS/flex-shrink)).
61+
<br/><br/>
62+
<em>Notice: when the value is set to `true/false` or `0/1` a CSS class is used to apply the `flex-shrink` property; in all the other cases an inline `style` declaration is used, to accomodate for all the possible values that this CSS property allows.</em>
63+
</C.Property>
64+
<C.Property @name="enableCollapseBelowContentSize" @type="boolean">
65+
When this special argument is set to `true` it applies a `min-width: 0` to the element, allowing the flex item to shrink below its content's intrinsic minimum width (e.g. used with elliptized text)
66+
<br/><br/>
67+
<em>Notice: this may have accessibility implications, be considerate in how this special argument is used and how this impacts the content of the flex item element.</em>
68+
</C.Property>
69+
<C.Property @name="yield">
70+
Elements passed as children are yielded as inner content of the element.
71+
</C.Property>
72+
<C.Property @name="...attributes">
73+
This component supports use of [`...attributes`](https://guides.emberjs.com/release/in-depth-topics/patterns-for-components/#toc_attribute-ordering).
74+
</C.Property>
75+
</Doc::ComponentApi>

‎website/docs/layouts/flex/partials/code/how-to-use.md

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
## How to use this component
2+
3+
TODO
4+
5+
### TODO
6+
7+
TODO
8+
9+
## Examples
10+
11+
Below some examples of common layouts.

‎website/docs/layouts/flex/partials/version-history/version-history.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
## 4.19.0
2+
3+
TODO

0 commit comments

Comments
 (0)