@@ -54,42 +54,127 @@ Ref<T> createRef<T>() {
5454
5555/// Automatically passes a [Ref] through a component to one of its children.
5656///
57- /// __Example__:
57+ /// __Example 1:__ Forwarding refs to DOM components
58+ ///
59+ /// ```dart
60+ /// import 'dart:html';
61+ /// import 'package:over_react/over_react.dart';
62+ /// import 'package:over_react/react_dom.dart' as react_dom;
63+ ///
64+ /// // ---------- Component Definition ----------
65+ ///
66+ /// final FancyButton = forwardRef<DomProps>((props, ref) {
67+ /// final classes = ClassNameBuilder.fromProps(props)
68+ /// ..add('FancyButton');
69+ ///
70+ /// return (Dom.button()
71+ /// ..addProps(getPropsToForward(props, onlyCopyDomProps: true))
72+ /// ..className = classes.toClassName()
73+ /// ..ref = ref
74+ /// )('Click me!');
75+ /// })(Dom.button);
76+ ///
77+ /// // ---------- Component Consumption ----------
78+ ///
79+ /// void main() {
80+ /// setClientConfiguration();
81+ /// final ref = createRef<Element>();
5882///
59- /// UiFactory<DomProps> DivForwarded = forwardRef<DomProps>((props, ref) {
60- /// return (Dom.div ()
83+ /// react_dom.render(
84+ /// (FancyButton ()
6185/// ..ref = ref
62- /// ..className = 'special-class'
63- /// )(
64- /// props.children
65- /// );
66- /// })(Dom.div);
86+ /// ..onClick = (_) {
87+ /// print(ref.current.outerHtml);
88+ /// }
89+ /// )(),
90+ /// querySelector('#idOfSomeNodeInTheDom')
91+ /// );
6792///
68- /// ___ OR ___
93+ /// // You can still get a ref directly to the DOM button:
94+ /// final buttonNode = ref.current;
95+ /// }
96+ /// ```
6997///
70- /// UiFactory<FooProps> FooForwarded = forwardRef<FooProps>((props, ref) {
71- /// return (Foo()
72- /// ..forwardedRef = ref
73- /// )();
74- /// })(Foo);
98+ /// __Example 2:__ Forwarding refs in higher-order components
7599///
76- /// @Factory()
77- /// UiFactory<FooProps> Foo = _$Foo;
100+ /// ```dart
101+ /// import 'dart:html';
102+ /// import 'package:over_react/over_react.dart';
103+ /// import 'package:over_react/react_dom.dart' as react_dom;
78104///
79- /// @Props()
80- /// class _$FooProps extends UiProps {
81- /// Ref forwardedRef;
82- /// }
105+ /// // ---------- Component Definitions ----------
83106///
84- /// @Component2()
85- /// class FooComponent extends UiComponent2<FooProps> {
86- /// @override
87- /// render() {
88- /// return (Dom.button()
89- /// ..ref = props.forwardedRef
90- /// )('Click this button');
91- /// }
92- /// }
107+ /// final FancyButton = forwardRef<DomProps>((props, ref) {
108+ /// final classes = ClassNameBuilder.fromProps(props)
109+ /// ..add('FancyButton');
110+ ///
111+ /// return (Dom.button()
112+ /// ..addProps(getPropsToForward(props, onlyCopyDomProps: true))
113+ /// ..className = classes.toClassName()
114+ /// ..ref = ref
115+ /// )('Click me!');
116+ /// })(Dom.button);
117+ ///
118+ /// final LogProps = forwardRef<LogPropsProps>((props, ref) {
119+ /// return (_LogProps()
120+ /// ..addProps(props)
121+ /// .._forwardedRef = ref
122+ /// )('Click me!');
123+ /// })(_LogProps);
124+ ///
125+ /// @Factory()
126+ /// UiFactory<LogPropsProps> _LogProps = _$_LogProps;
127+ ///
128+ /// @Props()
129+ /// class _$LogPropsProps extends UiProps {
130+ /// BuilderOnlyUiFactory<DomProps> builder;
131+ ///
132+ /// // Private since we only use this to pass along the value of `ref` to
133+ /// // the return value of forwardRef.
134+ /// //
135+ /// // Consumers can set this private field value using the public `ref` setter.
136+ /// Ref _forwardedRef;
137+ /// }
138+ ///
139+ /// @Component2()
140+ /// class LogPropsComponent extends UiComponent2<LogPropsProps> {
141+ /// @override
142+ /// void componentDidUpdate(Map prevProps, _, [__]) {
143+ /// print('old props: $prevProps');
144+ /// print('new props: $props');
145+ /// }
146+ ///
147+ /// @override
148+ /// render() {
149+ /// return (props.builder()
150+ /// ..modifyProps(addUnconsumedDomProps)
151+ /// ..ref = props._forwardedRef
152+ /// )(props.children);
153+ /// }
154+ /// }
155+ ///
156+ /// // ---------- Component Consumption ----------
157+ ///
158+ /// void main() {
159+ /// setClientConfiguration();
160+ /// final ref = createRef<Element>();
161+ ///
162+ /// react_dom.render(
163+ /// (LogProps()
164+ /// ..builder = FancyButton
165+ /// ..className = 'btn btn-primary'
166+ /// ..ref = ref
167+ /// ..onClick = (_) {
168+ /// print(ref.current.outerHtml);
169+ /// }
170+ /// )(),
171+ /// querySelector('#idOfSomeNodeInTheDom')
172+ /// );
173+ ///
174+ /// // You can still get a ref directly to the DOM button:
175+ /// final buttonNode = ref.current;
176+ /// }
177+ /// ```
93178///
94179/// Learn more: <https://reactjs.org/docs/forwarding-refs.html>.
95180UiFactory <TProps > Function (UiFactory <TProps >) forwardRef <TProps extends UiProps >(
0 commit comments