Add components examples in README.md files - Part 2 (#8338)

* Components examples: Modal * Components examples: Modal * Components examples assigned to const variables * Components examples: Notice * Components examples: Panel * Components examples: Placeholder * Components examples: Popover * Components examples: QueryControls * Components examples: RadioControl * Components examples: RangeControl * Components examples: ResponsiveWrapper * Components examples: SandBox * Components examples: ScrollLock * Components examples: SelectControl * Components examples: ServerSideRender * Add metadata using YAML front matter so examples can be extracted dynamically * Add metadata using YAML front matter so examples can be extracted dynamically * Remove YAML front matter * Components examples: SlotFill * Components examples: Spinner * Components examples: TabPanel * Components examples: TextControl * Components examples: TextareaControl * Components examples: ToggleControl * Components examples: Toolbar * Components examples: Tooltip * Components examples: TreeSelect * Components examples: NavigableContainer * Components examples: navigateRegions * Components examples: withConstrainedTabbing * Components examples: withContext * Components examples: withFallbackStyles * Components examples: withFilters * Components examples: withFocusOutside * Components examples: withFocusReturn * Components examples: withNotices * Components examples: withSpokenMessages * Components examples: withAPIData * Contributing guidelines for the components * Contributing guidelines for the components * Contributing guidelines for the components * Add dummy attributes to ServerSideRender example
WordPress · Aug 8, 2018 · 5b81cbc · 5b81cbc
1 parent 8cbc988
commit 5b81cbc
Show file tree

Hide file tree

Showing 61 changed files with 768 additions and 452 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -154,6 +154,10 @@ Documentation is automatically synced from master to the [Gutenberg Documentatio
 
 To add a new documentation page, you'll have to create a Markdown file in the [docs](https://github.com/WordPress/gutenberg/tree/master/docs) folder and add an item to the [manifest file](https://github.com/WordPress/gutenberg/blob/master/docs/manifest.json).
 
+### `@wordpress/component`
+
+If you're contributing to the documentation of any component from the `@wordpress/component` package, take a look at its [guidelines for contributing](./packages/components/CONTRIBUTING.md). 
+
 ## Reporting Security Issues
 
 Please see [SECURITY.md](./SECURITY.md).

diff --git a/packages/components/CONTRIBUTING.md b/packages/components/CONTRIBUTING.md
@@ -0,0 +1,15 @@
+# Contributing
+
+Thank you for taking the time to contribute.
+
+The following is a set of guidelines for contributing to the `@wordpress/components` package to be considered in addition to the general ones described in our [Contributing Policy](../../CONTRIBUTING.md).
+
+## Examples
+
+Each component needs to include an example in its README.md file to demonstrate the usage of the component.
+
+These examples can be consumed automatically from other projects in order to visualize them in their documentation. To ensure these examples are extractable, compilable and renderable, they should be structured in the following way:
+
+* It has to be included in a `jsx` code block.
+* It has to work out-of-the-box. No additional code should be needed to have working the example.
+* It has to define a React component called `My<ComponentName>` which renders the example (i.e.: `MyButton`). Examples for the Higher Order Components should define a `MyComponent<ComponentName>` component (i.e.: `MyComponentWithNotices`). 
diff --git a/packages/components/src/autocomplete/README.md b/packages/components/src/autocomplete/README.md
@@ -111,7 +111,7 @@ The following is a contrived completer for fresh fruit.
 ```jsx
 import { Autocomplete } from '@wordpress/components';
 
-function FreshFruitAutocomplete() {
+const MyAutocomplete = () => {
 	const autocompleters = [
 		{
 			name: 'fruit',

diff --git a/packages/components/src/base-control/README.md b/packages/components/src/base-control/README.md
@@ -9,19 +9,17 @@ Render a BaseControl for a textarea input:
 ```jsx
 import { BaseControl } from '@wordpress/components';
 
-function MyBaseControl() {
-	return (
-		<BaseControl
+const MyBaseControl = () => (
+	<BaseControl
+		id="textarea-1"
+		label="Text"
+		help="Enter some text"
+	>
+		<textarea
 			id="textarea-1"
-			label="Text"
-			help="Enter some text"
-		>
-			<textarea
-				id="textarea-1"
-			/>
-		</BaseControl>
-    );
-}
+		/>
+	</BaseControl>
+);
 ```
 
 ## Props

diff --git a/packages/components/src/button-group/README.md b/packages/components/src/button-group/README.md
@@ -5,12 +5,10 @@
 ```jsx
 import { Button, ButtonGroup } from '@wordpress/components';
 
-function MyButtonGroup() {
-	return (
-		<ButtonGroup>
-			<Button isPrimary>Button 1</Button>
-			<Button isPrimary>Button 2</Button>
-		</ButtonGroup>
-	);
-}
+const MyButtonGroup = () => (
+	<ButtonGroup>
+		<Button isPrimary>Button 1</Button>
+		<Button isPrimary>Button 2</Button>
+	</ButtonGroup>
+);
 ```
diff --git a/packages/components/src/button/README.md b/packages/components/src/button/README.md
@@ -11,13 +11,11 @@ Renders a button with default style.
 ```jsx
 import { Button } from "@wordpress/components";
 
-function MyButton() {
-	return (
-		<Button isDefault>
-			Click me!
-		</Button>
-	);
-}
+const MyButton = () => (
+	<Button isDefault>
+		Click me!
+	</Button>
+);
 ```
 
 ## Props

diff --git a/packages/components/src/checkbox-control/README.md b/packages/components/src/checkbox-control/README.md
@@ -10,7 +10,7 @@ Render an is author checkbox:
 import { CheckboxControl } from '@wordpress/components';
 import { withState } from '@wordpress/compose';
 
-withState( {
+const MyCheckboxControl = withState( {
 	isChecked: true,
 } )( ( { isChecked, setState } ) => ( 
 	<CheckboxControl
@@ -20,7 +20,7 @@ withState( {
 		checked={ isChecked }
 		onChange={ ( isChecked ) => { setState( { isChecked } ) } }
 	/>
-) )
+) );
 ```
 
 ## Props

diff --git a/packages/components/src/clipboard-button/README.md b/packages/components/src/clipboard-button/README.md
@@ -6,7 +6,7 @@
 import { ClipboardButton } from '@wordpress/components';
 import { withState } from '@wordpress/compose';
 
-withState( {
+const MyClipboardButton = withState( {
 	hasCopied: false,
 } )( ( { hasCopied, setState } ) => ( 
 	<ClipboardButton

diff --git a/packages/components/src/color-indicator/README.md b/packages/components/src/color-indicator/README.md
@@ -5,9 +5,7 @@
 ```jsx
 import { ColorIndicator } from '@wordpress/components';
 
-function MyColorIndicator() {
-	return (
-		<ColorIndicator colorValue="#f00" />
-	);
-}
+const MyColorIndicator = () => (
+	<ColorIndicator colorValue="#f00" />
+);
 ```
diff --git a/packages/components/src/color-palette/README.md b/packages/components/src/color-palette/README.md
@@ -5,7 +5,7 @@
 import { ColorPalette } from '@wordpress/components';
 import { withState } from '@wordpress/compose';
 
-withState( {
+const MyColorPalette = withState( {
 	color: '#f00',
 } )( ( { color, setState } ) => { 
 	const colors = [ 
@@ -18,8 +18,8 @@ withState( {
 		<ColorPalette 
 			colors={ colors } 
 			value={ color }
-			onChange={ color => setState( { color } ) } 
+			onChange={ ( color ) => setState( { color } ) } 
 		/>
 	) 
-} )
+} );
 ```
diff --git a/packages/components/src/dashicon/README.md b/packages/components/src/dashicon/README.md
@@ -5,13 +5,11 @@
 ```jsx
 import { Dashicon } from '@wordpress/components';
 
-function MyDashicons() {
-	return (
-		<div>
-			<Dashicon icon="admin-home" />
-			<Dashicon icon="products" />
-			<Dashicon icon="wordpress" />
-		</div>
-	);
-}
+const MyDashicon = () => (
+	<div>
+		<Dashicon icon="admin-home" />
+		<Dashicon icon="products" />
+		<Dashicon icon="wordpress" />
+	</div>
+);
 ```
diff --git a/packages/components/src/date-time/README.md b/packages/components/src/date-time/README.md
@@ -9,8 +9,12 @@ Render a DateTimePicker.
 ```jsx
 import { DateTimePicker } from '@wordpress/components';
 import { getSettings } from '@wordpress/date';
+import { withState } from '@wordpress/compose';
 
-function selectTime( date, onUpdateDate ) {
+
+const MyDateTimePicker = withState( {
+	date: new Date(),
+} )( ( { date, setState } ) => {
 	const settings = getSettings();
 
 	// To know if the current timezone is a 12 hour time with look for "a" in the time format.
@@ -25,12 +29,12 @@ function selectTime( date, onUpdateDate ) {
 	return (
 		<DateTimePicker
 		    currentDate={ date }
-		    onChange={ onUpdateDate }
+		    onChange={ ( date ) => setState( { date } ) }
 		    locale={ settings.l10n.locale }
 		    is12Hour={ is12HourTime }
 		    />
 	);
-}
+} );
 ```
 
 ## Props

diff --git a/packages/components/src/disabled/README.md b/packages/components/src/disabled/README.md
@@ -10,7 +10,7 @@ Assuming you have a form component, you can disable all form inputs by wrapping
 import { Button, Disabled, TextControl } from '@wordpress/components';
 import { withState } from '@wordpress/compose';
 
-withState( {
+const MyDisabled = withState( {
 	isDisabled: true,
 } )( ( { isDisabled, setState } ) => { 
 	let input = <TextControl label="Input" onChange={ () => {} } />;
@@ -30,7 +30,7 @@ withState( {
 			</Button>
 		</div>
 	);
-} )
+} );
 ```
 
 A component can detect if it has been wrapped in a `<Disabled>` by accessing its [context](https://reactjs.org/docs/context.html) using `Disabled.Consumer`.

diff --git a/packages/components/src/draggable/README.md b/packages/components/src/draggable/README.md
@@ -41,20 +41,18 @@ The function called when dragging ends.
 ```jsx
 import { Dashicon, Draggable, Panel, PanelBody } from '@wordpress/components';
 
-function DraggablePanel() {
-	return (
-		<div id="draggable-panel">
-			<Panel header="Draggable panel" >
-				<PanelBody>
-					<Draggable
-						elementId="draggable-panel"
-						transferData={ { } }
-					>
-						<Dashicon icon="move" />
-					</Draggable>
-				</PanelBody>
-			</Panel>
-		</div>
-	);
-}
+const MyDraggable = () => (
+	<div id="draggable-panel">
+		<Panel header="Draggable panel" >
+			<PanelBody>
+				<Draggable
+					elementId="draggable-panel"
+					transferData={ { } }
+				>
+					<Dashicon icon="move" />
+				</Draggable>
+			</PanelBody>
+		</Panel>
+	</div>
+);
 ```
diff --git a/packages/components/src/drop-zone/README.md b/packages/components/src/drop-zone/README.md
@@ -8,7 +8,7 @@
 import { DropZoneProvider, DropZone } from '@wordpress/components';
 import { withState } from '@wordpress/compose';
 
-withState( {
+const MyDropZone = withState( {
 	hasDropped: false,
 } )( ( { hasDropped, setState } ) => (
 	<DropZoneProvider>

diff --git a/packages/components/src/dropdown-menu/README.md b/packages/components/src/dropdown-menu/README.md
@@ -9,36 +9,34 @@ Render a Dropdown Menu with a set of controls:
 ```jsx
 import { DropdownMenu } from '@wordpress/components';
 
-function DirectionMenu() {
-	return (
-		<DropdownMenu
-			icon="move"
-			label="Select a direction"
-			controls={ [
-				{
-					title: 'Up',
-					icon: 'arrow-up-alt',
-					onClick: () => console.log( 'up' )
-				},
-				{
-					title: 'Right',
-					icon: 'arrow-right-alt',
-					onClick: () => console.log( 'right' )
-				},
-				{
-					title: 'Down',
-					icon: 'arrow-down-alt',
-					onClick: () => console.log( 'down' )
-				},
-				{
-					title: 'Left',
-					icon: 'arrow-left-alt',
-					onClick: () => console.log( 'left' )
-				},
-			] }
-		/>
-	);
-}
+const MyDropdownMenu = () => (
+	<DropdownMenu
+		icon="move"
+		label="Select a direction"
+		controls={ [
+			{
+				title: 'Up',
+				icon: 'arrow-up-alt',
+				onClick: () => console.log( 'up' )
+			},
+			{
+				title: 'Right',
+				icon: 'arrow-right-alt',
+				onClick: () => console.log( 'right' )
+			},
+			{
+				title: 'Down',
+				icon: 'arrow-down-alt',
+				onClick: () => console.log( 'down' )
+			},
+			{
+				title: 'Left',
+				icon: 'arrow-left-alt',
+				onClick: () => console.log( 'left' )
+			},
+		] }
+	/>
+);
 ```
 
 ## Props

diff --git a/packages/components/src/dropdown/README.md b/packages/components/src/dropdown/README.md
@@ -10,25 +10,23 @@ and uses render props to render the button and the content.
 ```jsx
 import { Button, Dropdown } from '@wordpress/components';
 
-function MyDropdownMenu() {
-	return (
-		<Dropdown
-			className="my-container-class-name"
-			contentClassName="my-popover-content-classname"
-			position="bottom right"
-			renderToggle={ ( { isOpen, onToggle } ) => (
-				<Button isPrimary onClick={ onToggle } aria-expanded={ isOpen }>
-					Toggle Popover!
-				</Button>
-			) }
-			renderContent={ () => (
-				<div>
-					This is the content of the popover.
-				</div>
-			) }
-		/>
-	);
-}
+const MyDropdown = () => (
+	<Dropdown
+		className="my-container-class-name"
+		contentClassName="my-popover-content-classname"
+		position="bottom right"
+		renderToggle={ ( { isOpen, onToggle } ) => (
+			<Button isPrimary onClick={ onToggle } aria-expanded={ isOpen }>
+				Toggle Popover!
+			</Button>
+		) }
+		renderContent={ () => (
+			<div>
+				This is the content of the popover.
+			</div>
+		) }
+	/>
+);
 ```
 
 ## Props

diff --git a/packages/components/src/external-link/README.md b/packages/components/src/external-link/README.md
@@ -5,9 +5,7 @@
 ```jsx
 import { ExternalLink } from '@wordpress/components';
 
-function MyExternalLink() {
-	return (
-		<ExternalLink href="https://wordpress.org">WordPress.org</ExternalLink>
-	);
-}
+const MyExternalLink = () => (
+	<ExternalLink href="https://wordpress.org">WordPress.org</ExternalLink>
+);
 ```