From 84924e446278af2317da903cf4e2cb4282dd85e9 Mon Sep 17 00:00:00 2001
From: Grzegorz Ziolkowski <grzegorz@gziolo.pl>
Date: Wed, 31 Oct 2018 16:11:00 +0100
Subject: [PATCH] Docs: Extends docs for withFilters HOC

---
 gutenberg-mobile                              |  2 +-
 .../src/higher-order/with-filters/README.md   | 59 +++++++++++++++----
 2 files changed, 48 insertions(+), 13 deletions(-)

diff --git a/gutenberg-mobile b/gutenberg-mobile
index 776bb23f7f19ef..c90c36410d4c0c 160000
--- a/gutenberg-mobile
+++ b/gutenberg-mobile
@@ -1 +1 @@
-Subproject commit 776bb23f7f19ef57b491f9708e9795b3a2ddb68e
+Subproject commit c90c36410d4c0c3f2dea84ca666b1b585408a03f
diff --git a/packages/components/src/higher-order/with-filters/README.md b/packages/components/src/higher-order/with-filters/README.md
index 244b226445c16d..3baa46c085313e 100644
--- a/packages/components/src/higher-order/with-filters/README.md
+++ b/packages/components/src/higher-order/with-filters/README.md
@@ -7,25 +7,60 @@ Wrapping a component with `withFilters` provides a filtering capability controll
 ## Usage
 
 ```jsx
-import { withFilters } from '@wordpress/components';
+import { Fragment, withFilters } from '@wordpress/components';
 import { addFilter } from '@wordpress/hooks';
 
-const ComposedComponent = () => <div>Composed component</div>;
+const MyComponent = ( { title } ) => <h1>{ title }</h1>;
+
+const ComponentToAppend = () => <div>Appended component</div>;
+
+function withComponentApended( FilteredComponent ) {
+	return ( props ) => (
+        <Fragment>
+            <FilteredComponent { ...props } />
+            <ComponentToAppend />
+        </Fragment>
+    );
+}
 
 addFilter(
 	'MyHookName',
-	'example/filtered-component',
-	( FilteredComponent ) => () => (
-		<div>
-			<FilteredComponent />
-			<ComposedComponent />
-		</div>
-	)
+	'my-plugin/with-component-appended',
+	withComponentApended
 );
 
-const MyComponentWithFilters = withFilters( 'MyHookName' )( 
-	() => <div>My component</div> 
-);
+const MyComponentWithFilters = withFilters( 'MyHookName' )( MyComponent );
 ```
 
 `withFilters` expects a string argument which provides a hook name. It returns a function which can then be used in composing your component. The hook name allows plugin developers to customize or completely override the component passed to this higher-order component using `wp.hooks.addFilter` method.
+
+It is also possible to override props by implementing a higher-order component which works as follows:
+
+```jsx
+import { Fragment, withFilters } from '@wordpress/components';
+import { addFilter } from '@wordpress/hooks';
+
+const MyComponent = ( { hint, title } ) => (
+    <Fragment>
+        <h1>{ title }</h1>
+        <p>{ hint }</p>
+    </Fragment> 
+);
+
+function withHintOverriden( FilteredComponent ) {
+	return ( props ) => (
+        <FilteredComponent
+            { ...props }
+            hint="Overriden hint"
+        />
+    );
+ }
+
+addFilter(
+    'MyHookName',
+    'my-plugin/with-hint-overriden',
+    withHintOverriden
+);
+
+const MyComponentWithFilters = withFilters( 'MyHookName' )( MyComponent );
+```