Skip to content
Permalink
Browse files

feat(website): aspect-ratio docs page (#104)

* feat(website): aspect-ratio docs page

* feat(website): aspect-ratio doc examples

* feat(website): removing text from aspect-ratio doc

* feat(website): aspect-ratio doc limit example width

* fix(website): use token for changelog margin

* fix(website): aspect-ratio, anchor, button docs text edits

* fix(website): nuke image example on aspect-ratio page

* fix(website): aspect-ratio doc page text and example changes

* fix(website): prettier formatting

* fix(website): remove iframe global style

* fix(aspect-ratio): add iframe, embed, object, video styles

* fix(website): refreshing yarn lock file

* fix(website): aspect ratio doc page text change

* fix(website): change react-helmet import
  • Loading branch information...
richbachman committed Sep 27, 2019
1 parent 3060113 commit 7a78689891468180929bb3cea45207ac09699f81
@@ -25,6 +25,17 @@ const handlePropValidation = ({ratio}: AspectRatioProps): void => {

const AspectRatioContainer = styled.div`
position: relative;
embed,
iframe,
object,
video {
position: absolute;
top: 0;
left: 0;
height: 100%;
width: 100%;
}
`;

const AspectRatio: React.FC<AspectRatioProps> = props => {
@@ -120,13 +120,17 @@ You can use an anchor to navigate the user to another webpage.
<content>
## Installation
## Usage Guide
### API
#### Installation
```bash
yarn add @twilio-paste/anchor
```
### Usage
#### Usage
```js
import {Anchor} from '@twilio-paste/anchor';
@@ -136,12 +140,7 @@ import {Anchor} from '@twilio-paste/anchor';
</Anchor>
```
### Storybook
[View Anchor in Storybook](https://twilio-labs.github.io/paste/?path=/story/components-anchor--default)
### Props
#### Props
| Prop | Type | Description | Default |
| -------------- | -------------------------------------- | ----------------------------------------------------------------------------------- | --------- |
@@ -153,7 +152,7 @@ import {Anchor} from '@twilio-paste/anchor';
| onFocus? | `(event: React.FocusEvent<HTMLElement>)` | | null |
| onBlur? | `(event: React.FocusEvent<HTMLElement>)` | | null |
<Box marginTop={30}>
<Box marginTop="space90">
<Changelog />
</Box>
@@ -365,15 +365,17 @@ right in an English-language flow).
<content>
## API
## Usage Guide
### Installation
### API
#### Installation
```bash
yarn add @twilio-paste/button
```

### Usage
#### Usage

```jsx
import {Button} from '@twilio-paste/button';
@@ -383,11 +385,7 @@ import {Button} from '@twilio-paste/button';
</Button>
```

### Storybook

[View Button in Storybook](https://twilio-labs.github.io/paste/?path=/story/components-button--text-only)

### Props
#### Props

| Prop | Type | Description | Default |
| -------------- | ---------------------------------------- | ----------------------------------------------------------------------------------- | --------- |
@@ -411,7 +409,7 @@ import {Button} from '@twilio-paste/button';
| aria-controls? | string | A11y: For modals and menus | null |
| data-test? | string | To detect the element to run tests against. | null |

<Box marginTop={30}>
<Box marginTop="space90">
<Changelog />
</Box>

@@ -1,5 +1,5 @@
import * as React from 'react';
import Helmet from 'react-helmet';
import {Helmet} from 'react-helmet';
import styled from '@emotion/styled';
import {themeGet} from 'styled-system';
import {Link} from 'gatsby';
@@ -0,0 +1,175 @@
---
title: Aspect Ratio - Utilities
package: '@twilio-paste/aspect-ratio'
description: The Aspect Ratio utility is used to embed images, video, media, components, or other HTML elements. It prevents skewing, cropping, etc.
---

import {graphql} from 'gatsby';
import Img from 'gatsby-image';
import {Anchor} from '@twilio-paste/anchor';
import {Absolute} from '@twilio-paste/absolute';
import {AspectRatio} from '@twilio-paste/aspect-ratio';
import {Box} from '@twilio-paste/box';
import Changelog from '@twilio-paste/aspect-ratio/CHANGELOG.md';
import {DoDont, Do, Dont} from '../../../components/DoDont';
import {SidebarCategoryRoutes} from '../../../constants';

export const pageQuery = graphql`
{
allPasteUtility(filter: {name: {eq: "@twilio-paste/aspect-ratio"}}) {
edges {
node {
name
description
status
version
}
}
}
file(sourceInstanceName: {eq: "assets"}, relativePath: {eq: "images/anchor-dont-1@4x.png"}) {
childImageSharp {
fluid(maxWidth: 500) {
...GatsbyImageSharpFluid
}
}
}
}
`;
<ComponentHeader
name="Aspect Ratio"
categoryRoute={SidebarCategoryRoutes.UTILITIES}
githubUrl="https://github.com/twilio-labs/paste/tree/master/packages/paste-core/utilities/aspect-ratio"
storybookUrl="https://twilio-labs.github.io/paste/?path=/story/utilities-aspect-ratio--default"
data={props.data.allPasteUtility.edges}
/>
***
<content>
## Guidelines
### About Aspect Ratio
The Aspect Ratio component dynamically modifies the height of an element based on its
current width to match a width-to-height ratio. For example, a 4:3 ratio would make
an element with a width of 400px have a height of 300px. This updates in real time
when you resize the screen.
## Composition Notes
Aspect Ratio must contain exactly one child element. The child element should be sized
fully to the Aspect Ratio bounding box so that it resizes correctly. One way of achieving
this is through the [Absolute](/utilities/absolute) component.
Be considerate of smaller devices when using this component. If necessary, you can
modify the aspect ratio property at certain media query breakpoints.
### When to use Aspect Ratio
Aspect Ratio can be used to embed images and videos.
Use Aspect Ratio to make sure images and videos are scaled correctly on
displays of various sizes. For example, you can use Aspect Ratio when a
customer needs to see a preview of an uploaded document.
<LivePreview scope={{Absolute, AspectRatio, Box}} language="jsx">
{`<Box
padding="space30"
maxWidth="size60"
borderColor="colorBorderLight"
borderStyle="solid"
borderWidth="borderWidth10"
>
<AspectRatio ratio="16:9">
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/euJAcVfn0C4" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
</AspectRatio>
</Box>`}
</LivePreview>
Aspect Ratio can also be used to embed components, or other HTML elements that
needs to be set to a specific width-to-height ratio. A component or other HTML
element use case is the need to align an HTML element with an image in two columns.
<LivePreview scope={{Absolute, Anchor, AspectRatio, Box}} language="jsx">
{`<Box
padding="space30"
maxWidth="size50"
borderColor="colorBorderLight"
borderStyle="solid"
borderWidth="borderWidth10"
>
<AspectRatio ratio="4:3">
<Absolute style={{display: 'flex', alignItems: 'center', justifyContent: 'center'}}>
<Anchor href="https://paste.twilio.design">Go to API documentation</Anchor>
</Absolute>
</AspectRatio>
</Box>`}
</LivePreview>
Another use case is for color swatches on a documentation site. These color swatches
could be a specific height/width div that need to resize on specific devices.
Aspect Ratio will allow the color swatches to resize correctly based on a ratio.
<LivePreview scope={{Absolute, AspectRatio, Box}} language="jsx">
{`<Box
padding="space30"
maxWidth="size50"
borderColor="colorBorderLight"
borderStyle="solid"
borderWidth="borderWidth10"
>
<AspectRatio ratio="4:3">
<Absolute backgroundColor="colorBackgroundBrand" />
</AspectRatio>
</Box>`}
</LivePreview>
<DoDont>
<Do title="Do" body="Use for an image or embedded video, and have it resize at a specific ratio." preview={false} />
<Dont title="Don't" body="Don’t use with fixed size (width & height) elements, as those will not adhere to the width-to-height ratio." preview={false} />
</DoDont>
<DoDont>
<Do title="Do" body="Use to embed a component or other HTML element." preview={false} />
<Dont title="Don't" body="Don’t use without any child elements, because this is only a container element." preview={false} />
</DoDont>
</content>
***
<content>
## Usage Guide
### API
#### Installation
```bash
yarn add @twilio-paste/aspect-ratio
```
#### Usage

```js
import {AspectRatio} from '@twilio-paste/aspect-ratio';
<AspectRatio ratio="4:3">
<Absolute>Test</Absolute>
</AspectRatio>
```

#### Props

| Prop | Type | Description | Default |
| -------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------ | --------- |
| ratio | string | Determines the aspect ratio of the element. Use a colon separated number pattern (width:height). Required | 4:3 |

<Box marginTop="space90">
<Changelog />
</Box>

</content>

1 comment on commit 7a78689

@now

This comment has been minimized.

Please sign in to comment.
You can’t perform that action at this time.