Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(CodeSnippet): overhaul storybook #6606

Merged
merged 14 commits into from
Aug 20, 2020
Merged

docs(CodeSnippet): overhaul storybook #6606

Show file tree
Hide file tree
Changes from 11 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
d8cc0dc
docs(CodeSnippet): overhaul storybook
dakahn Aug 4, 2020
d5e6e0b
docs(CodeSnippet): add mdx doc
dakahn Aug 6, 2020
37b864a
docs(CodeSnippet): add mdx doc
dakahn Aug 6, 2020
52f756d
docs(CodeSnippet): add <Story> components to mdx
dakahn Aug 11, 2020
1ba9674
docs(CodeSnippet): add single, multi, inline stories
dakahn Aug 19, 2020
273ef6b
docs(CodeSnippet): fix merge conflicts
dakahn Aug 19, 2020
60cf893
docs(CodeSnippet): fix ToC bug
dakahn Aug 19, 2020
77b5190
Merge branch 'master' into 6592-update-codesnippet-docs
tw15egan Aug 20, 2020
abab5bc
docs(CodeSnippet): add copy blurb, remove unneeded stories
dakahn Aug 20, 2020
3bd58b6
Merge branch '6592-update-codesnippet-docs' of github.com:dakahn/carb…
dakahn Aug 20, 2020
eaf9f2a
Merge branch 'master' into 6592-update-codesnippet-docs
dakahn Aug 20, 2020
0632ea2
docs(CodenSnippet): remove light example
dakahn Aug 20, 2020
4c044b8
Merge branch '6592-update-codesnippet-docs' of github.com:dakahn/carb…
dakahn Aug 20, 2020
3ce6c12
Merge branch 'master' into 6592-update-codesnippet-docs
dakahn Aug 20, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
234 changes: 66 additions & 168 deletions packages/react/src/components/CodeSnippet/CodeSnippet-story.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,51 +7,50 @@

import React from 'react';
import { action } from '@storybook/addon-actions';
import { withKnobs, boolean, text } from '@storybook/addon-knobs';
import { withKnobs, boolean, text, select } from '@storybook/addon-knobs';
import CodeSnippet from '../CodeSnippet';
import CodeSnippetSkeleton from './CodeSnippet.Skeleton';
import mdx from './CodeSnippet.mdx';

const props = {
inline: () => ({
light: boolean('Light variant (light)', false),
feedback: text('Feedback text (feedback)', 'Copied to clipboard'),
onClick: action('onClick'),
copyLabel: text(
'ARIA label for the snippet/copy button (copyLabel)',
'copyable code snippet'
),
hideCopyButton: boolean('Hide copy button (hideCopyButton)', false),
}),
single: () => ({
light: boolean('Light variant (light)', false),
feedback: text('Feedback text (feedback)', 'Copied to clipboard'),
copyButtonDescription: text(
'Copy icon description (copyButtonDescription)',
'copyable code snippet'
),
ariaLabel: text(
'ARIA label of the container (ariaLabel)',
'Container label'
),
hideCopyButton: boolean('Hide copy button (hideCopyButton)', false),
onClick: action('onClick'),
}),
multiline: () => ({
light: boolean('Light variant (light)', false),
feedback: text('Feedback text (feedback)', 'Copied to clipboard'),
showMoreText: text(
'Text for "show more" button (showMoreText)',
'Show more'
),
showLessText: text(
'Text for "show less" button (showLessText)',
'Show less'
),
hideCopyButton: boolean('Hide copy button (hideCopyButton)', false),
onClick: action('onClick'),
}),
export default {
title: 'CodeSnippet',
component: CodeSnippet,
decorators: [withKnobs],
parameters: {
docs: {
page: mdx,
},
},
};

export const inline = () => (
<CodeSnippet type="inline" feedback="Copied to clipboard">
{'node -v'}
</CodeSnippet>
);

export const multiline = () => (
<CodeSnippet type="multi" feedback="Copied to clipboard">
{`@mixin grid-container {
width: 100%;
padding-right: padding(mobile);
padding-left: padding(mobile);`}
</CodeSnippet>
);

export const singleline = () => (
<CodeSnippet type="single" feedback="Copied to clipboard">
{'node -v'}
</CodeSnippet>
);

export const skeleton = () => (
<div style={{ width: '800px' }}>
<CodeSnippetSkeleton type="single" style={{ marginBottom: 8 }} />
<CodeSnippetSkeleton type="multi" />
</div>
);

const lightPropMessage = (
<small style={{ display: 'block', paddingBottom: '1rem' }}>
The snippet container should never be the same color as the page background.
Expand All @@ -72,134 +71,33 @@ const lightPropMessage = (
</small>
);

export default {
title: 'CodeSnippet',
decorators: [withKnobs],

parameters: {
component: CodeSnippet,

subcomponents: {
CodeSnippetSkeleton,
},
},
};

export const Inline = () => (
<div className={props.inline().light ? 'bx--tile' : ''}>
{props.inline().light && lightPropMessage}
<CodeSnippet type="inline" {...props.inline()}>
{'node -v'}
</CodeSnippet>
</div>
);

Inline.storyName = 'inline';

Inline.parameters = {
info: {
text: `
Code snippets are small blocks of reusable code that can be inserted in a code file.

The Inline style is for code used within a block of text.
`,
},
};

export const SingleLine = () => (
<div className={props.single().light ? 'bx--tile' : ''}>
{props.single().light && lightPropMessage}
<CodeSnippet type="single" {...props.single()}>
{
'node -v Lorem ipsum dolor sit amet, consectetur adipisicing elit. Blanditiis, veritatis voluptate id incidunt molestiae officia possimus, quasi itaque alias, architecto hic, dicta fugit? Debitis delectus quidem explicabo vitae fuga laboriosam!'
}
const props = () => ({
type: select('Type', {
inline: 'inline',
'single line': 'single',
'multiple line': 'multi',
}),
light: boolean('Light variant', false),
feedback: text('Feedback text', 'Copied to clipboard'),
showMoreText: text('Text for "show more" button', 'Show more'),
showLessText: text('Text for "show less" button', 'Show less'),
hideCopyButton: boolean('Hide copy button', false),
onClick: action('onClick'),
copyButtonDescription: text('Copy button title', 'Copy code snippet'),
ariaLabel: text('ARIA label', 'Container label'),
});

export const playground = () => (
<div className={props().light ? 'bx--tile' : ''} style={{ width: '800px' }}>
{props().light && lightPropMessage}
<CodeSnippet {...props()}>
{props().type === 'multi'
? `@mixin grid-container {
width: 100%;
padding-right: padding(mobile);
padding-left: padding(mobile);
}`
: 'node -v'}
</CodeSnippet>
</div>
);

SingleLine.storyName = 'single line';

SingleLine.parameters = {
info: {
text: `
Code snippets are small blocks of reusable code that can be inserted in a code file.

The Code style is for larger, multi-line code snippets.
`,
},
};

export const MultiLine = () => {
const multilineProps = props.multiline();
return (
<div
className={multilineProps.light ? 'bx--tile' : ''}
style={{ width: '800px' }}>
{multilineProps.light && lightPropMessage}
<CodeSnippet type="multi" {...multilineProps}>
{`@mixin grid-container {
width: 100%;
padding-right: padding(mobile);
padding-left: padding(mobile);

@include breakpoint(bp--xs--major) {
padding-right: padding(xs);
padding-left: padding(xs);
}
}

$z-indexes: (
modal : 9000,
overlay : 8000,
dropdown : 7000,
header : 6000,
footer : 5000,
hidden : - 1,
overflowHidden: - 1,
floating: 10000
);`}
</CodeSnippet>
<br />
<CodeSnippet type="multi" {...multilineProps}>
{`@mixin grid-container {
width: 100%;
padding-right: padding(mobile);
padding-left: padding(mobile);

@include breakpoint(bp--xs--major) {
padding-right: padding(xs);
}
}`}
</CodeSnippet>
</div>
);
};

MultiLine.storyName = 'multi line';

MultiLine.parameters = {
info: {
text: `
Code snippets are small blocks of reusable code that can be inserted in a code file.

The Terminal style is for single-line .
`,
},
};

export const Skeleton = () => (
<div style={{ width: '800px' }}>
<CodeSnippetSkeleton type="single" style={{ marginBottom: 8 }} />
<CodeSnippetSkeleton type="multi" />
</div>
);

Skeleton.storyName = 'skeleton';

Skeleton.parameters = {
info: {
text: `
Placeholder skeleton state to use when content is loading.
`,
},
};
88 changes: 88 additions & 0 deletions packages/react/src/components/CodeSnippet/CodeSnippet.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
import { Story, Props, Source, Preview } from '@storybook/addon-docs/blocks';
import { withKnobs, boolean, select, text } from '@storybook/addon-knobs';
import * as stories from './CodeSnippet-story.js';
import CodeSnippet from '../CodeSnippet';

<!-- How do I get <Props> to work?
-->
dakahn marked this conversation as resolved.
Show resolved Hide resolved

# CodeSnippet
dakahn marked this conversation as resolved.
Show resolved Hide resolved

## Table of Contents

- [Overview](#overview)
- [Skeleton state](#skeleton-state)
- [Inline](#inline)
- [Multi-line](#multi-line)
- [Single-line](#single-line)
- [Light variant](#light-variant)
- [Component API](#component-api)
- [Feedback](#feedback)

## Overview

Code snippets are strings or small blocks of reusable code that are copyable. We
don't provide the copy functionality and recommend
[clipboard.js](https://clipboardjs.com/).

<Preview>
<Story id="codesnippet--inline" />
</Preview>

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It'd be helpful to talk about the different variations as top-level headings, maybe the following each with their own default example:

  • Inline
  • Multi-line
  • Single-line

At a top-level, it might be helpful to address a couple of common situations:

  • Copying a code snippet
    • How to enable/disable
    • How to configure the feedback provided
  • Rendering a "light" variant, and when/why to use that

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added individual sections for the different use cases (inline, multi, light etc) -- seemed a little redundant to describe turning the copy button off and on and stuff with the API and expected boolean listed in the props table though, but I can go back and add that if we think it's something we need.

## Skeleton state

You can use the `CodeSnippetSkeleton` component to render a skeleton variant of
an code snippet. This is useful to display while content in your code snippet is
being fetched from an external resource like an API.

<Preview>
<Story id="codesnippet--skeleton" />
</Preview>

## Inline

Inline code snippet's are used for distinguishing a symbol, variable, function
name or similar small piece of code from it's surrounding text.

<Preview>
<Story id="codesnippet--inline" />
</Preview>

## Multi-line

Multiple line code snippets are used for displaying code with more than one
line. They're shown in a block and useful for showing classes, functions, blocks
of styles and the like.

<Preview>
<Story id="codesnippet--multiline" />
</Preview>

## Single-line

Single line code snippets are used when showing code that fits on one line
without wrapping. Useful for calling out terminal commands, function
invocations, expressions etc.

<Preview>
<Story id="codesnippet--singleline" />
</Preview>

## Light variant
dakahn marked this conversation as resolved.
Show resolved Hide resolved

Use the light prop modifier when using a code snippet on a background other than
the UI background for that theme. The light prop changes the background color
token of the code snippet from `field-01` to `field-02`.

<Preview>
<Story id="codesnippet--inline" light />
</Preview>
dakahn marked this conversation as resolved.
Show resolved Hide resolved

## Component API

<Props sort="asc" />

joshblack marked this conversation as resolved.
Show resolved Hide resolved
## Feedback
dakahn marked this conversation as resolved.
Show resolved Hide resolved

Help us improve these docs by
[editing this file on GitHub](https://github.com/carbon-design-system/carbon/edit/master/packages/react/src/components/CodeSnippet/CodeSnippet.stories.mdx)