docs: Component Rules #1055

dgodinez-dh · 2024-12-04T15:10:44Z

DOC-204

dsmmcken · 2024-12-04T15:14:28Z

plugins/ui/docs/describing/component_rules.md

+
+## Component Return Values
+
+You can return three values from a `deephaven.ui` component: a component, a list of components, or `None`. Returning a single component will render that component at the root level of a panel. Returning a list of components will render all the components in a panel. Returning `None` should be used when a component is used to perform logic but does not need to be rendered.


@mofojed this isn't true? For instance you can also return hooks.

I did not know you could return hooks from a component. Can you also return primitive values like strings, numbers, and booleans?

@dsmmcken What do you mean return hooks? You can return the result of a hook, but returning the hook itself doesn't make sense (ditto in React). The result of the hook could be a component, list of components, None, or a primitive.
You can also return primitives though, such as str, int, boolean.

I pushed an update. I'm still not sure if this is saying what we want.

Also, I tested dict and set. They do not open up a panel.
With bool, it opens a panel, but does not render anything (where string and int get rendered).

Yes that's correct. I don't know why you'd want to return a boolean (since it doesn't get rendered), but React does allow you to do that.
Returning a dict or a set could possibly give you an error. There's a little playground at the bottom of the React page where you can play with what are valid returns, we should match that: https://react.dev/learn/your-first-component

Is there a way to add a code playground in our docs? Can we do that in an md file?

We want to do that, it will not be in the first deployment.
With React Playground it's nice because it all runs client side. We need to have a server running for our playground, so setup is a little more complicated. Probably use a running instance that's shared between all viewers of the docs.

What do you mean return hooks? You can return the result of a hook,

Yeah, that's what I meant, like return [my_state, my_set_state]

@dsmmcken doing return [my_state, my_set_state] does not make sense from a component. You can do that from other hooks, but that doesn't make sense in React or in deephaven.ui.
You can do return my_state. You wouldn't return the setter function.

plugins/ui/docs/describing/component_rules.md

Co-authored-by: Mike Bender <[email protected]>

margaretkennedy · 2024-12-06T16:24:30Z

plugins/ui/docs/describing/component_rules.md

+my_component("Hello World", prop1="value1")
+```
+
+## Defining Your Own Children and Props


sentence case for headings, please

plugins/ui/docs/describing/component_rules.md

margaretkennedy

Looks good to me after the typo fix is committed.

Co-authored-by: margaretkennedy <[email protected]>

plugins/ui/docs/describing/component_rules.md

jjbrosnan

Only one comment for now, since my next questions are what are at the forefront of my mind as I read this.

What's the reason this and other PRs are not in the docs repo? Do we really expect users to know to come here to read about deephaven.ui? This also won't render and look nice like everything else on the docs site.

Co-authored-by: JJ Brosnan <[email protected]>

dgodinez-dh · 2024-12-09T21:27:00Z

Only one comment for now, since my next questions are what are at the forefront of my mind as I read this.

What's the reason this and other PRs are not in the docs repo? Do we really expect users to know to come here to read about deephaven.ui? This also won't render and look nice like everything else on the docs site.

@dsmmcken Can you reply to our docs strategy?

dsmmcken · 2024-12-10T14:49:21Z

What's the reason this and other PRs are not in the docs repo? Do we really expect users to know to come here to read about deephaven.ui? This also won't render and look nice like everything else on the docs site.

@jjbrosnan It will render in salmon. That's one of the neat design goals behind it. Let's us keep all the docs next to the code where they can stay updated and be used for testing, but still assemble it up into a single docs site.

plugins/ui/docs/describing/component_rules.md

jjbrosnan · 2024-12-10T17:30:19Z

plugins/ui/docs/describing/component_rules.md

+
+## Children and props
+
+Arguments passed to a component may be either `children` or `props`. `Children` refers to `child` components that are passed to a `parent` component as positional arguments. `Props` are properties passed as keyword arguments that determine the behavior and rendering style of the component. Positional arguments must be included in the correct order. Keyword arguments are included with a keyword and equals sign.


Worth noting that keyword argument ordering doesn't matter, but that ordering of keyword arguments can affect ordering of positional arguments and make them out of order?

jjbrosnan · 2024-12-10T17:30:49Z

plugins/ui/docs/describing/component_rules.md

+
+Arguments passed to a component may be either `children` or `props`. `Children` refers to `child` components that are passed to a `parent` component as positional arguments. `Props` are properties passed as keyword arguments that determine the behavior and rendering style of the component. Positional arguments must be included in the correct order. Keyword arguments are included with a keyword and equals sign.
+
+```python


Image of the output?

@dsmmcken will this be testable with the snapshot tool if this doesn't live in docs?

jjbrosnan · 2024-12-10T17:31:45Z

plugins/ui/docs/describing/component_rules.md

+
+In the above example, the `flex` component is the `parent`. It has three `children`: a `heading`, a `button`, and a `text` component. These `children` will be rendered inside the `flex`. It also has three props: `direction`, `wrap`, and `width`. These three props indicate that the flex should be rendered as a 200 pixel column with wrap enabled.
+
+## Comparison with JSX


I don't understand the purpose of this section. What component rule does this demonstrate?

@mofojed Requested a comparison with JSX.

The purpose is showing users familiar with React how to modify this for DH, but an intro sentence saying as much would be useful.

jjbrosnan · 2024-12-10T17:33:15Z

plugins/ui/docs/describing/component_rules.md

+
+To define `children` and `props` for a custom component, add them as arguments to the component function. As a convention, you may declare the children using the `*` symbol to take any number of arguments.
+
+```python


An image of the component would be good to have.

jjbrosnan · 2024-12-10T17:34:43Z

plugins/ui/docs/describing/component_rules.md

+
+## Component return values
+
+A `deephaven.ui` component usually returns a component. It may also return a list or tuple of components. It may return `None` if it should perform logic but does not need to be rendered. It may also return a single value like a `string` or `int`.


Does this differ at all from any other Python UDF?

Yes. A Python UDF can return any value. A deephaven.ui component is limited in valid return values.

jjbrosnan · 2024-12-10T17:35:12Z

plugins/ui/docs/describing/component_rules.md

+
+my_button = return_conditional(True)
+my_text = return_conditional(False)
+```


Related documentation?

I can link to conditional rendering. All that section has not been created yet.

The plugins / deephaven.ui docs don't have a Related docs section; so either all of them need it, or we agree not to include it for now.

All of the docs in this repo will eventually be rendered on the docs site. All of the pages on there have related documentation at the bottom. These should have it.

jjbrosnan · 2024-12-10T17:35:26Z

plugins/ui/docs/describing/component_rules.md

+my_return_int = return_int()
+```
+
+## Conditional return


This section feels like the same topic as the previous. Any reason not to just combine them?

The previous section is about valid return values. This section is about returning different values based on a condition. I think it is clearer in two different sections.

jjbrosnan

Several comments.

Co-authored-by: JJ Brosnan <[email protected]>

plugins/ui/docs/describing/component_rules.md

margaretkennedy · 2024-12-11T18:02:13Z

plugins/ui/docs/describing/component_rules.md

+
+In the above example, the `flex` component is the `parent`. It has three `children`: a `heading`, a `button`, and a `text` component. These `children` will be rendered inside the `flex`. It also has three props: `direction`, `wrap`, and `width`. These three props indicate that the flex should be rendered as a 200 pixel column with wrap enabled.
+
+## Comparison with JSX


The purpose is showing users familiar with React how to modify this for DH, but an intro sentence saying as much would be useful.

plugins/ui/docs/describing/component_rules.md

margaretkennedy · 2024-12-11T18:04:31Z

plugins/ui/docs/describing/component_rules.md

+
+my_button = return_conditional(True)
+my_text = return_conditional(False)
+```


The plugins / deephaven.ui docs don't have a Related docs section; so either all of them need it, or we agree not to include it for now.

plugins/ui/docs/describing/component_rules.md

Co-authored-by: margaretkennedy <[email protected]>

docs: Component Rules

e8f2a76

dgodinez-dh requested a review from dsmmcken December 4, 2024 15:10

github-actions bot requested a review from margaretkennedy December 4, 2024 15:10

dsmmcken reviewed Dec 4, 2024

View reviewed changes

dgodinez-dh added 2 commits December 4, 2024 08:39

update return values

1a2c0ea

fix merge

0899527

mofojed requested changes Dec 4, 2024

View reviewed changes

plugins/ui/docs/describing/component_rules.md Outdated Show resolved Hide resolved

dgodinez-dh and others added 2 commits December 4, 2024 14:16

Update plugins/ui/docs/describing/component_rules.md

ddd7bcc

Co-authored-by: Mike Bender <[email protected]>

jsx example

048adae

dgodinez-dh requested a review from mofojed December 4, 2024 21:52

fix merge

646c4ff

mofojed previously approved these changes Dec 6, 2024

View reviewed changes

margaretkennedy reviewed Dec 6, 2024

View reviewed changes

sentence casing

6c52c75

dgodinez-dh dismissed mofojed’s stale review via 6c52c75 December 6, 2024 16:36

dgodinez-dh requested a review from margaretkennedy December 6, 2024 16:36

margaretkennedy reviewed Dec 6, 2024

View reviewed changes

plugins/ui/docs/describing/component_rules.md Outdated Show resolved Hide resolved

margaretkennedy reviewed Dec 6, 2024

View reviewed changes

Update plugins/ui/docs/describing/component_rules.md

cec0436

Co-authored-by: margaretkennedy <[email protected]>

dgodinez-dh requested a review from margaretkennedy December 9, 2024 20:40

margaretkennedy previously approved these changes Dec 9, 2024

View reviewed changes

jjbrosnan reviewed Dec 9, 2024

View reviewed changes

plugins/ui/docs/describing/component_rules.md Outdated Show resolved Hide resolved

jjbrosnan reviewed Dec 9, 2024

View reviewed changes

Apply suggestions from code review

5c943b8

Co-authored-by: JJ Brosnan <[email protected]>

dgodinez-dh dismissed margaretkennedy’s stale review via 5c943b8 December 9, 2024 21:25

dgodinez-dh requested a review from jjbrosnan December 9, 2024 21:27

jjbrosnan reviewed Dec 10, 2024

View reviewed changes

plugins/ui/docs/describing/component_rules.md Outdated Show resolved Hide resolved

jjbrosnan reviewed Dec 10, 2024

View reviewed changes

Apply suggestions from code review

31c8348

Co-authored-by: JJ Brosnan <[email protected]>

margaretkennedy changed the title ~~docs: Component Rules~~ DOC-204: Component Rules Dec 10, 2024

margaretkennedy changed the title ~~DOC-204: Component Rules~~ docs: Component Rules Dec 10, 2024

review comments

0943739

dgodinez-dh requested a review from jjbrosnan December 10, 2024 19:45

fix merge

411c9ee

dgodinez-dh requested a review from margaretkennedy December 11, 2024 14:21

margaretkennedy reviewed Dec 11, 2024

View reviewed changes

dgodinez-dh and others added 2 commits December 11, 2024 12:04

Apply suggestions from code review

24aef92

Co-authored-by: margaretkennedy <[email protected]>

review changes

ad5b922

dgodinez-dh requested a review from margaretkennedy December 11, 2024 19:19

merge latest

887cba8


		## Component Return Values

		You can return three values from a `deephaven.ui` component: a component, a list of components, or `None`. Returning a single component will render that component at the root level of a panel. Returning a list of components will render all the components in a panel. Returning `None` should be used when a component is used to perform logic but does not need to be rendered.


		## Children and props

		Arguments passed to a component may be either `children` or `props`. `Children` refers to `child` components that are passed to a `parent` component as positional arguments. `Props` are properties passed as keyword arguments that determine the behavior and rendering style of the component. Positional arguments must be included in the correct order. Keyword arguments are included with a keyword and equals sign.


		Arguments passed to a component may be either `children` or `props`. `Children` refers to `child` components that are passed to a `parent` component as positional arguments. `Props` are properties passed as keyword arguments that determine the behavior and rendering style of the component. Positional arguments must be included in the correct order. Keyword arguments are included with a keyword and equals sign.

		```python


		In the above example, the `flex` component is the `parent`. It has three `children`: a `heading`, a `button`, and a `text` component. These `children` will be rendered inside the `flex`. It also has three props: `direction`, `wrap`, and `width`. These three props indicate that the flex should be rendered as a 200 pixel column with wrap enabled.

		## Comparison with JSX


		To define `children` and `props` for a custom component, add them as arguments to the component function. As a convention, you may declare the children using the `*` symbol to take any number of arguments.

		```python


		## Component return values

		A `deephaven.ui` component usually returns a component. It may also return a list or tuple of components. It may return `None` if it should perform logic but does not need to be rendered. It may also return a single value like a `string` or `int`.

docs: Component Rules #1055

Are you sure you want to change the base?

docs: Component Rules #1055

Conversation

dgodinez-dh commented Dec 4, 2024 • edited by mofojed Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

margaretkennedy left a comment

Choose a reason for hiding this comment

jjbrosnan left a comment

Choose a reason for hiding this comment

dgodinez-dh commented Dec 9, 2024

dsmmcken commented Dec 10, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jjbrosnan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dgodinez-dh commented Dec 4, 2024 •

edited by mofojed

Loading

dsmmcken commented Dec 10, 2024 •

edited

Loading