dioxus_core/
properties.rs

1use std::{any::TypeId, fmt::Arguments};
2
3use crate::innerlude::*;
4
5/// Every "Props" used for a component must implement the `Properties` trait. This trait gives some hints to Dioxus
6/// on how to memoize the props and some additional optimizations that can be made. We strongly encourage using the
7/// derive macro to implement the `Properties` trait automatically.
8///
9/// Dioxus requires your props to be 'static, `Clone`, and `PartialEq`. We use the `PartialEq` trait to determine if
10/// the props have changed when we diff the component.
11///
12/// ## Example
13///
14/// ```rust
15/// # use dioxus::prelude::*;
16/// #[derive(Props, PartialEq, Clone)]
17/// struct MyComponentProps {
18///     data: String
19/// }
20///
21/// fn MyComponent(props: MyComponentProps) -> Element {
22///     rsx! {
23///         div { "Hello {props.data}" }
24///     }
25/// }
26/// ```
27///
28/// Or even better, derive your entire props struct with the [`#[crate::component]`] macro:
29///
30/// ```rust
31/// # use dioxus::prelude::*;
32/// #[component]
33/// fn MyComponent(data: String) -> Element {
34///     rsx! {
35///         div { "Hello {data}" }
36///     }
37/// }
38/// ```
39#[rustversion::attr(
40    since(1.78.0),
41    diagnostic::on_unimplemented(
42        message = "`Props` is not implemented for `{Self}`",
43        label = "Props",
44        note = "Props is a trait that is automatically implemented for all structs that can be used as props for a component",
45        note = "If you manually created a new properties struct, you may have forgotten to add `#[derive(Props, PartialEq, Clone)]` to your struct",
46    )
47)]
48pub trait Properties: Clone + Sized + 'static {
49    /// The type of the builder for this component.
50    /// Used to create "in-progress" versions of the props.
51    type Builder;
52
53    /// Create a builder for this component.
54    fn builder() -> Self::Builder;
55
56    /// Make the old props equal to the new props. Return if the props were equal and should be memoized.
57    fn memoize(&mut self, other: &Self) -> bool;
58
59    /// Create a component from the props.
60    fn into_vcomponent<M: 'static>(self, render_fn: impl ComponentFunction<Self, M>) -> VComponent {
61        let type_name = std::any::type_name_of_val(&render_fn);
62        VComponent::new(render_fn, self, type_name)
63    }
64}
65
66impl Properties for () {
67    type Builder = EmptyBuilder;
68    fn builder() -> Self::Builder {
69        EmptyBuilder {}
70    }
71    fn memoize(&mut self, _other: &Self) -> bool {
72        true
73    }
74}
75
76/// Root properties never need to be memoized, so we can use a dummy implementation.
77pub(crate) struct RootProps<P>(pub P);
78
79impl<P> Clone for RootProps<P>
80where
81    P: Clone,
82{
83    fn clone(&self) -> Self {
84        Self(self.0.clone())
85    }
86}
87
88impl<P> Properties for RootProps<P>
89where
90    P: Clone + 'static,
91{
92    type Builder = P;
93    fn builder() -> Self::Builder {
94        unreachable!("Root props technically are never built")
95    }
96    fn memoize(&mut self, _other: &Self) -> bool {
97        true
98    }
99}
100
101// We allow components to use the () generic parameter if they have no props. This impl enables the "build" method
102// that the macros use to anonymously complete prop construction.
103pub struct EmptyBuilder;
104impl EmptyBuilder {
105    pub fn build(self) {}
106}
107
108/// This utility function launches the builder method so that the rsx! macro can use the typed-builder pattern
109/// to initialize a component's props.
110pub fn fc_to_builder<P, M>(_: impl ComponentFunction<P, M>) -> <P as Properties>::Builder
111where
112    P: Properties,
113{
114    P::builder()
115}
116
117/// A warning that will trigger if a component is called as a function
118#[warnings::warning]
119pub(crate) fn component_called_as_function<C: ComponentFunction<P, M>, P, M>(_: C) {
120    // We trim WithOwner from the end of the type name for component with a builder that include a special owner which may not match the function name directly
121    let type_name = std::any::type_name::<C>();
122    let component_name = Runtime::with(|rt| {
123        current_scope_id()
124            .ok()
125            .and_then(|id| rt.get_state(id).map(|scope| scope.name))
126    })
127    .ok()
128    .flatten();
129
130    // If we are in a component, and the type name is the same as the active component name, then we can just return
131    if component_name == Some(type_name) {
132        return;
133    }
134
135    // Otherwise the component was called like a function, so we should log an error
136    tracing::error!("It looks like you called the component {type_name} like a function instead of a component. Components should be called with braces like `{type_name} {{ prop: value }}` instead of as a function");
137}
138
139/// Make sure that this component is currently running as a component, not a function call
140#[doc(hidden)]
141#[allow(clippy::no_effect)]
142pub fn verify_component_called_as_component<C: ComponentFunction<P, M>, P, M>(component: C) {
143    component_called_as_function(component);
144}
145
146/// Any component that implements the `ComponentFn` trait can be used as a component.
147///
148/// This trait is automatically implemented for functions that are in one of the following forms:
149/// - `fn() -> Element`
150/// - `fn(props: Properties) -> Element`
151///
152/// You can derive it automatically for any function with arguments that implement PartialEq with the `#[component]` attribute:
153/// ```rust
154/// # use dioxus::prelude::*;
155/// #[component]
156/// fn MyComponent(a: u32, b: u32) -> Element {
157///     rsx! { "a: {a}, b: {b}" }
158/// }
159/// ```
160#[rustversion::attr(
161    since(1.78.0),
162    diagnostic::on_unimplemented(
163        message = "`Component<{Props}>` is not implemented for `{Self}`",
164        label = "Component",
165        note = "Components are functions in the form `fn() -> Element`, `fn(props: Properties) -> Element`, or `#[component] fn(partial_eq1: u32, partial_eq2: u32) -> Element`.",
166        note = "You may have forgotten to add `#[component]` to your function to automatically implement the `ComponentFunction` trait."
167    )
168)]
169pub trait ComponentFunction<Props, Marker = ()>: Clone + 'static {
170    /// Get the type id of the component.
171    fn id(&self) -> TypeId {
172        TypeId::of::<Self>()
173    }
174
175    /// Convert the component to a function that takes props and returns an element.
176    fn rebuild(&self, props: Props) -> Element;
177}
178
179/// Accept any callbacks that take props
180impl<F: Fn(P) -> Element + Clone + 'static, P> ComponentFunction<P> for F {
181    fn rebuild(&self, props: P) -> Element {
182        self(props)
183    }
184}
185
186/// Accept any callbacks that take no props
187pub struct EmptyMarker;
188impl<F: Fn() -> Element + Clone + 'static> ComponentFunction<(), EmptyMarker> for F {
189    fn rebuild(&self, _: ()) -> Element {
190        self()
191    }
192}
193
194/// A enhanced version of the `Into` trait that allows with more flexibility.
195pub trait SuperInto<O, M = ()> {
196    /// Convert from a type to another type.
197    fn super_into(self) -> O;
198}
199
200impl<T, O, M> SuperInto<O, M> for T
201where
202    O: SuperFrom<T, M>,
203{
204    fn super_into(self) -> O {
205        O::super_from(self)
206    }
207}
208
209/// A enhanced version of the `From` trait that allows with more flexibility.
210pub trait SuperFrom<T, M = ()> {
211    /// Convert from a type to another type.
212    fn super_from(_: T) -> Self;
213}
214
215// first implement for all types that are that implement the From trait
216impl<T, O> SuperFrom<T, ()> for O
217where
218    O: From<T>,
219{
220    fn super_from(input: T) -> Self {
221        Self::from(input)
222    }
223}
224
225#[doc(hidden)]
226pub struct OptionStringFromMarker;
227
228impl<'a> SuperFrom<&'a str, OptionStringFromMarker> for Option<String> {
229    fn super_from(input: &'a str) -> Self {
230        Some(String::from(input))
231    }
232}
233
234#[doc(hidden)]
235pub struct OptionArgumentsFromMarker;
236
237impl<'a> SuperFrom<Arguments<'a>, OptionArgumentsFromMarker> for Option<String> {
238    fn super_from(input: Arguments<'a>) -> Self {
239        Some(input.to_string())
240    }
241}
242
243#[doc(hidden)]
244pub struct OptionCallbackMarker<T>(std::marker::PhantomData<T>);
245
246// Closure can be created from FnMut -> async { anything } or FnMut -> Ret
247impl<
248        Function: FnMut(Args) -> Spawn + 'static,
249        Args: 'static,
250        Spawn: SpawnIfAsync<Marker, Ret> + 'static,
251        Ret: 'static,
252        Marker,
253    > SuperFrom<Function, OptionCallbackMarker<Marker>> for Option<Callback<Args, Ret>>
254{
255    fn super_from(input: Function) -> Self {
256        Some(Callback::new(input))
257    }
258}
259
260#[test]
261#[allow(unused)]
262fn optional_callback_compiles() {
263    fn compiles() {
264        // Converting from closures (without type hints in the closure works)
265        let callback: Callback<i32, i32> = (|num| num * num).super_into();
266        let callback: Callback<i32, ()> = (|num| async move { println!("{num}") }).super_into();
267
268        // Converting from closures to optional callbacks works
269        let optional: Option<Callback<i32, i32>> = (|num| num * num).super_into();
270        let optional: Option<Callback<i32, ()>> =
271            (|num| async move { println!("{num}") }).super_into();
272    }
273}
274
275#[test]
276#[allow(unused)]
277fn from_props_compiles() {
278    // T -> T works
279    let option: i32 = 0i32.super_into();
280    let option: i32 = 0.super_into(); // Note we don't need type hints on all inputs
281    let option: i128 = 0.super_into();
282    let option: &'static str = "hello world".super_into();
283
284    // // T -> From<T> works
285    let option: i64 = 0i32.super_into();
286    let option: String = "hello world".super_into();
287
288    // T -> Option works
289    let option: Option<i32> = 0i32.super_into();
290    let option: Option<i32> = 0.super_into();
291    let option: Option<i128> = 0.super_into();
292    fn takes_option_string<M>(_: impl SuperInto<Option<String>, M>) {}
293    takes_option_string("hello world");
294    takes_option_string("hello world".to_string());
295}