From 26f6641ae4edbe60882487d64fb8a55e3d74b70f Mon Sep 17 00:00:00 2001 From: ebectar Date: Thu, 6 Dec 2018 11:04:45 -0700 Subject: [PATCH 1/2] docs(fix): reorganized usage guide for new users --- docs/src/pages/Usage.mdx | 81 +++++++++++++++++++++------------------- 1 file changed, 43 insertions(+), 38 deletions(-) diff --git a/docs/src/pages/Usage.mdx b/docs/src/pages/Usage.mdx index c98bb5fd67..c7b0c2ac48 100644 --- a/docs/src/pages/Usage.mdx +++ b/docs/src/pages/Usage.mdx @@ -1,11 +1,7 @@ import { Button, Header, List, Message } from 'semantic-ui-react' import CodeSnippet from 'docs/src/components/CodeSnippet' -import { - semanticUIDocsURL, - semanticUIRepoURL, - semanticUICSSRepoURL, -} from 'docs/src/utils' +import { semanticUIDocsURL, semanticUIRepoURL, semanticUICSSRepoURL } from 'docs/src/utils' export const meta = { title: 'Usage', @@ -13,36 +9,36 @@ export const meta = {
-## JavaScript - -The Semantic UI React package can be installed via Yarn: - - - -Installing Semantic UI React provides the JavaScript for your components. You'll also need +Semantic UI React provides the JavaScript for your components. You'll also need to include a stylesheet to provide the styling for your components. This is the typical pattern for component frameworks, such as Semantic UI or Bootstrap. The method you choose to include the stylesheet in your project will depend on the level of customisation you require. -### Examples +
+ + +### Usage Examples For examples on how to import and use Semantic UI React components, click the code icon next to any example. Here are a few direct links: -* [Button](/elements/button#button-example-button) -* [List](/elements/list#list-example-list) -* [Card](/views/card#card-example-card) -* [Modal](/modules/modal#modal-example-modal) - -## CSS +- [Button](/elements/button#button-example-button) +- [List](/elements/list#list-example-list) +- [Card](/views/card#card-example-card) +- [Modal](/modules/modal#modal-example-modal) Semantic UI support

- The release 2.3 of Semantic UI introduced some backward incompatible changes, so you - should use corresponding version of Semantic UI React: + The release 2.3 of Semantic UI introduced some backward incompatible changes, so you should use + corresponding version of Semantic UI React:

for SUI 2.2 use 0.80.2 and below @@ -50,7 +46,11 @@ next to any example. Here are a few direct links: -### Content Delivery Network (CDN) +## Method 1: CDN + +The Semantic UI React package can be installed via Yarn (this provides the JavaScript for your components): + + You can use the default Semantic UI stylesheet by including a Semantic UI CDN link in your _index.html_ file. @@ -59,35 +59,40 @@ custom themes with this method. `} + value={``} /> -### Semantic UI CSS package +## Method 2: Semantic UI CSS package The Semantic UI CSS package is automatically synced with the main Semantic UI repository to provide a lightweight CSS only version of Semantic -UI. +UI. You won't be able to use custom themes with this method. -Semantic UI CSS can be installed as a package in your project using Yarn. You won't be able to use custom themes with this method. +The Semantic UI React package can be installed via Yarn (this provides the JavaScript for your components): + + + +Semantic UI CSS can be installed as a package in your project using Yarn (this provides the CSS package for your components). ```sh $ yarn add semantic-ui-css ``` After install, you'll need to include the minified CSS file in your _index.js_ file: - + ```jsx -import 'semantic-ui-css/semantic.min.css'; +import 'semantic-ui-css/semantic.min.css' ``` -### Semantic UI package - -Install the full Semantic UI package. +## Method 3: Semantic UI Bundler Package -Semantic UI includes Gulp build tools so your project can preserve its own theme changes, allowing you to customise the style variables. +The full Semantic UI package includes Gulp build tools so your project can preserve its own theme changes, allowing you to customise the style variables.

- Detailed documentation on theming in Semantic UI is provided here. + Detailed documentation on theming in Semantic UI is provided{' '} + here.

```sh @@ -97,11 +102,11 @@ $ yarn add semantic-ui --dev After building the project with Gulp, you'll need to include the minified CSS file in your _index.js_ file: ```jsx -import '../semantic/dist/semantic.min.css'; +import '../semantic/dist/semantic.min.css' ``` ## Bundlers - + Semantic UI React is fully supported by all modern JavaScript bundlers. We made some example recipes with some of them. You can use them as start point for your projects. @@ -112,8 +117,8 @@ build your app in production mode before release, it will strip `propTypes` from

- Webpack 2/3 tree shaking does not completely remove unused exports, there are numerous - issues that are long-standing bugs: + Webpack 2/3 tree shaking does not completely remove unused exports, there are numerous issues + that are long-standing bugs:

Date: Sun, 9 Dec 2018 14:46:38 -0800 Subject: [PATCH 2/2] docs: cleanup usage and code snippets --- .prettierrc.json | 7 + docs/src/components/CodeEditor/CodeEditor.js | 6 +- .../CodeEditor/CodeEditorUniveral.js | 3 +- .../src/components/CodeSnippet/CodeSnippet.js | 18 +- .../ComponentExample/ComponentExample.js | 12 +- .../ComponentExampleRenderEditor.js | 5 +- .../ComponentExampleRenderHtml.js | 8 +- .../DocumentationPage/DocumentationPage.js | 6 +- .../DocumentationPage/components.js | 6 +- docs/src/pages/Introduction.js | 30 +- docs/src/pages/Usage.mdx | 382 ++-- docs/src/utils/btoa.js | 8 - docs/src/utils/formatCode.js | 5 + docs/src/utils/index.js | 1 - package.json | 2 +- yarn.lock | 1903 +---------------- 16 files changed, 273 insertions(+), 2129 deletions(-) delete mode 100644 docs/src/utils/btoa.js diff --git a/.prettierrc.json b/.prettierrc.json index 6a6910e79b..14bedecbad 100644 --- a/.prettierrc.json +++ b/.prettierrc.json @@ -1,5 +1,6 @@ { "$schema": "http://json.schemastore.org/prettierrc", + "arrowParens": "always", "jsxSingleQuote": true, "printWidth": 100, "tabWidth": 2, @@ -18,6 +19,12 @@ "options": { "semi": true } + }, + { + "files": "docs/src/examples/**/*.js", + "options": { + "printWidth": 80 + } } ] } diff --git a/docs/src/components/CodeEditor/CodeEditor.js b/docs/src/components/CodeEditor/CodeEditor.js index 89875b59d9..9822e09a88 100644 --- a/docs/src/components/CodeEditor/CodeEditor.js +++ b/docs/src/components/CodeEditor/CodeEditor.js @@ -96,7 +96,11 @@ const semanticUIReactCompleter = { } const CodeEditor = props => ( - + ) export default CodeEditor diff --git a/docs/src/components/CodeEditor/CodeEditorUniveral.js b/docs/src/components/CodeEditor/CodeEditorUniveral.js index 0c03333773..6afd590c12 100644 --- a/docs/src/components/CodeEditor/CodeEditorUniveral.js +++ b/docs/src/components/CodeEditor/CodeEditorUniveral.js @@ -19,11 +19,10 @@ const CodeEditor = isBrowser() : () => null function CodeEditorUniveral(props) { - const { id, mode, readOnly, value, ...rest } = props + const { mode, readOnly, value, ...rest } = props return ( ( -
+const CodeSnippet = ({ fitted, label, mode, value, ...rest }) => ( +
{label || mode}
) CodeSnippet.propTypes = { + fitted: PropTypes.bool, label: PropTypes.string, mode: PropTypes.oneOf(['html', 'jsx', 'sh']).isRequired, value: PropTypes.string.isRequired, } +CodeSnippet.defaultProps = { + mode: 'jsx', +} + export default CodeSnippet diff --git a/docs/src/components/ComponentDoc/ComponentExample/ComponentExample.js b/docs/src/components/ComponentDoc/ComponentExample/ComponentExample.js index 641f2679e6..2d4dee5efd 100644 --- a/docs/src/components/ComponentDoc/ComponentExample/ComponentExample.js +++ b/docs/src/components/ComponentDoc/ComponentExample/ComponentExample.js @@ -172,7 +172,9 @@ class ComponentExample extends PureComponent { } getKebabExamplePath = () => { - if (!this.kebabExamplePath) this.kebabExamplePath = _.kebabCase(this.props.examplePath) + if (!this.kebabExamplePath) { + this.kebabExamplePath = _.kebabCase(this.props.examplePath) + } return this.kebabExamplePath } @@ -277,7 +279,6 @@ class ComponentExample extends PureComponent { {showCode && ( )} - {showHTML && ( - - )} + {showHTML && } )} {isActive && !error && } diff --git a/docs/src/components/ComponentDoc/ComponentExample/ComponentExampleRenderEditor.js b/docs/src/components/ComponentDoc/ComponentExample/ComponentExampleRenderEditor.js index 7fda547a85..3611372005 100644 --- a/docs/src/components/ComponentDoc/ComponentExample/ComponentExampleRenderEditor.js +++ b/docs/src/components/ComponentDoc/ComponentExample/ComponentExampleRenderEditor.js @@ -33,7 +33,6 @@ class ComponentExampleRenderEditor extends PureComponent { state = {} static propTypes = { - editorId: PropTypes.string.isRequired, examplePath: PropTypes.string.isRequired, githubEditHref: PropTypes.string.isRequired, onChange: PropTypes.func.isRequired, @@ -129,12 +128,12 @@ class ComponentExampleRenderEditor extends PureComponent { } render() { - const { editorId, error, onChange, value } = this.props + const { error, onChange, value } = this.props return (
{this.renderEditorMenu()} - + {error && ( {error} diff --git a/docs/src/components/ComponentDoc/ComponentExample/ComponentExampleRenderHtml.js b/docs/src/components/ComponentDoc/ComponentExample/ComponentExampleRenderHtml.js index 86982767a9..6548c04604 100644 --- a/docs/src/components/ComponentDoc/ComponentExample/ComponentExampleRenderHtml.js +++ b/docs/src/components/ComponentDoc/ComponentExample/ComponentExampleRenderHtml.js @@ -3,7 +3,6 @@ import React, { PureComponent } from 'react' import { Divider } from 'semantic-ui-react' import Editor, { EDITOR_BACKGROUND_COLOR } from 'docs/src/components/CodeEditor' -import formatCode from 'docs/src/utils/formatCode' const rootStyle = { padding: '1rem', @@ -16,22 +15,21 @@ const dividerStyle = { export default class ComponentExampleRenderHtml extends PureComponent { static propTypes = { - editorId: PropTypes.string.isRequired, value: PropTypes.string.isRequired, } render() { - const { editorId, value } = this.props + const { value } = this.props // remove new line at eof after formatting for a tighter fit - const formattedCode = formatCode(value, 'html').replace(/\s+$/, '') + const formattedCode = value.trim() return (
HTML - +
) } diff --git a/docs/src/components/DocumentationPage/DocumentationPage.js b/docs/src/components/DocumentationPage/DocumentationPage.js index 383151fd65..370c0c091e 100644 --- a/docs/src/components/DocumentationPage/DocumentationPage.js +++ b/docs/src/components/DocumentationPage/DocumentationPage.js @@ -1,7 +1,7 @@ import PropTypes from 'prop-types' import React from 'react' import { withRouteData, withSiteData } from 'react-static' -import { Container } from 'semantic-ui-react' +import { Container, Divider } from 'semantic-ui-react' import DocsLayout from 'docs/src/components/DocsLayout' import * as components from './components' @@ -11,8 +11,10 @@ const DocumentationPage = ({ pageName, ...rest }) => { return ( - + + ) diff --git a/docs/src/components/DocumentationPage/components.js b/docs/src/components/DocumentationPage/components.js index 4c2659d3fc..57f17d4a9f 100644 --- a/docs/src/components/DocumentationPage/components.js +++ b/docs/src/components/DocumentationPage/components.js @@ -1,4 +1,3 @@ -import _ from 'lodash' import React from 'react' import { Link } from 'react-static' import { Header } from 'semantic-ui-react' @@ -13,11 +12,10 @@ export const a = ({ children, href }) => {children} export const code = ({ className, children }) => { const mode = className.replace('language-', '') - const value = _.trim(children) - return + return } -export const h1 = ({ children }) =>
+export const h1 = ({ children }) =>
export const h2 = ({ children }) =>
diff --git a/docs/src/pages/Introduction.js b/docs/src/pages/Introduction.js index ba4e77a7df..8ab070365e 100644 --- a/docs/src/pages/Introduction.js +++ b/docs/src/pages/Introduction.js @@ -6,7 +6,7 @@ import { Container, Divider, Grid, Header, Icon, Label, List, Segment } from 'se import DocsLayout from 'docs/src/components/DocsLayout' import Editor from 'docs/src/components/CodeEditor' import Logo from 'docs/src/components/Logo/Logo' -import { btoa, semanticUIDocsURL, repoURL } from 'docs/src/utils' +import { semanticUIDocsURL, repoURL } from 'docs/src/utils' const AccordionJSX = `const panels = [{ title: 'What is a dog?', @@ -113,7 +113,7 @@ const Comparison = ({ jsx, html }) => ( - + @@ -124,7 +124,7 @@ const Comparison = ({ jsx, html }) => ( - + @@ -168,8 +168,8 @@ const Introduction = ({ pkg }) => ( {/* ---------------------------------------- - * jQuery Free - * -------------------------------------- */} + * jQuery Free + * -------------------------------------- */}
jQuery Free @@ -186,8 +186,8 @@ const Introduction = ({ pkg }) => ( {/* ---------------------------------------- - * Declarative API - * -------------------------------------- */} + * Declarative API + * -------------------------------------- */}
Declarative API @@ -199,8 +199,8 @@ const Introduction = ({ pkg }) => ( {/* ---------------------------------------- - * Augmentation - * -------------------------------------- */} + * Augmentation + * -------------------------------------- */}
Augmentation @@ -221,8 +221,8 @@ const Introduction = ({ pkg }) => ( {/* ---------------------------------------- - * Shorthand Props - * -------------------------------------- */} + * Shorthand Props + * -------------------------------------- */}
Shorthand Props @@ -262,8 +262,8 @@ const Introduction = ({ pkg }) => ( {/* ---------------------------------------- - * Sub Components - * -------------------------------------- */} + * Sub Components + * -------------------------------------- */}
Sub Components @@ -276,8 +276,8 @@ const Introduction = ({ pkg }) => ( {/* ---------------------------------------- - * Auto Controlled State - * -------------------------------------- */} + * Auto Controlled State + * -------------------------------------- */}
Auto Controlled State diff --git a/docs/src/pages/Usage.mdx b/docs/src/pages/Usage.mdx index c7b0c2ac48..f42ed8d154 100644 --- a/docs/src/pages/Usage.mdx +++ b/docs/src/pages/Usage.mdx @@ -1,4 +1,5 @@ -import { Button, Header, List, Message } from 'semantic-ui-react' +import { Link } from 'react-static' +import { Button, Divider, Header, Icon, List, Message, Segment, Tab } from 'semantic-ui-react' import CodeSnippet from 'docs/src/components/CodeSnippet' import { semanticUIDocsURL, semanticUIRepoURL, semanticUICSSRepoURL } from 'docs/src/utils' @@ -7,199 +8,214 @@ export const meta = { title: 'Usage', } -
+# Usage -Semantic UI React provides the JavaScript for your components. You'll also need -to include a stylesheet to provide the styling for your components. This is the typical -pattern for component frameworks, such as Semantic UI or Bootstrap. +## Install -The method you choose to include the stylesheet in your project will depend on the level -of customisation you require. +Semantic UI React provides React components while Semantic UI provides themes as CSS stylesheets. +Install the React components and choose a theme that suits your needs. -
- +### Components -### Usage Examples +React components can be installed via yarn: -For examples on how to import and use Semantic UI React components, click the code icon -next to any example. Here are a few direct links: - -- [Button](/elements/button#button-example-button) -- [List](/elements/list#list-example-list) -- [Card](/views/card#card-example-card) -- [Modal](/modules/modal#modal-example-modal) + - - Semantic UI support -

- The release 2.3 of Semantic UI introduced some backward incompatible changes, so you should use - corresponding version of Semantic UI React: -

- - for SUI 2.2 use 0.80.2 and below - for SUI 2.3 use 0.81.0 and higher - + + + Themes from Semantic UI >=2.3.x require Semantic UI React >=0.81.0. -## Method 1: CDN - -The Semantic UI React package can be installed via Yarn (this provides the JavaScript for your components): - - - -You can use the default Semantic UI stylesheet by including a Semantic UI CDN link in your _index.html_ file. - -This is the quickest way to get started with Semantic UI React. You won't be able to use -custom themes with this method. - -`} +### Theme + +Choose a theme and delivery method that suits your needs: + + ( + +

+ This is the quickest way to get started, just add this link to the{' '} + {''} of your index.html file. +

+ + `} + /> + + ), + }, + { + menuItem: 'Default theme (NPM)', + render: () => ( + +

+ The Semantic UI CSS package is automatically synced + with the main Semantic UI repository to provide a lightweight CSS only version of + Semantic UI. +

+ +

After install, import the minified CSS file in your app's entry file:

+ + + ), + }, + { + menuItem: 'Custom theme (NPM)', + render: () => ( + +

+ The Semantic UI package installs a Gulp build tool that + will walk you through creating a custom theme within your project. Install this as a dev + dependency: +

+ +

+ After building a theme with Gulp, include the minified CSS file in your{' '} + index.js file: +

+ +

+ Detailed documentation on Semantic UI theming is provided{' '} + here. +

+ + ), + }, + ]} /> -## Method 2: Semantic UI CSS package - -The Semantic UI CSS package is automatically synced -with the main Semantic UI repository to provide a lightweight CSS only version of Semantic -UI. You won't be able to use custom themes with this method. - -The Semantic UI React package can be installed via Yarn (this provides the JavaScript for your components): - - - -Semantic UI CSS can be installed as a package in your project using Yarn (this provides the CSS package for your components). - -```sh -$ yarn add semantic-ui-css -``` - -After install, you'll need to include the minified CSS file in your _index.js_ file: - -```jsx -import 'semantic-ui-css/semantic.min.css' -``` - -## Method 3: Semantic UI Bundler Package - -The full Semantic UI package includes Gulp build tools so your project can preserve its own theme changes, allowing you to customise the style variables. - -

- Detailed documentation on theming in Semantic UI is provided{' '} - here. -

- -```sh -$ yarn add semantic-ui --dev -``` - -After building the project with Gulp, you'll need to include the minified CSS file in your _index.js_ file: - -```jsx -import '../semantic/dist/semantic.min.css' -``` - -## Bundlers - -Semantic UI React is fully supported by all modern JavaScript bundlers. We made some -example recipes with some of them. You can use them as start point for your projects. - -### Webpack 2/3 - -Webpack 2/3 fully supports Semantic UI React, it also supports Tree Shaking. Please ensure that you -build your app in production mode before release, it will strip `propTypes` from your build. - - -

- Webpack 2/3 tree shaking does not completely remove unused exports, there are numerous issues - that are long-standing bugs: -

- - - webpack/webpack#1750 - - } - /> - - webpack/webpack#2867 - - } - /> - - webpack/webpack#2899 - - } - /> - - webpack/webpack#3092 - - } - /> - -

- Semantic UI React imports will be not optimized, so we recommend to use - babel-plugin-lodash in your builds. You can find example configuration in - examples/webpack3 directory. -

- - -