UI controls API improvements

[ovidiuch]

I'm in the process of improving the API of useValue (and potentially useSelect).

1) Accept default value as 2nd argument

At the moment the 2nd argument is an object with a defaultValue key. The original design was meant to allow future properties but we never added any and meanwhile the current API is more verbose than necessary.

-const [value, setValue] = useValue('my-value', { defaultValue: 'default' });
+const [value, setValue] = useValue('my-value', 'default');

This cleans up the code and also makes useValue closer to the standard useState.

2) Rename useValue to useCosmosState

First off, we pretty much need a new name for the useValue hook in order to preserve backwards compatibility when making change nr. 1. Because the default value could be an object with a defaultValue key, there's no way to distinguish reliably between the new and old APIs.

So while we're at it we might as well think of a better name going forward.

useCosmosState has a couple of advantages:

• It's more expressive and doesn't pollute the global namespace with something generic like useValue which could be present in other libraries or in the user's own codebase.
• It's more similar to useState and it resembles the API used in other libraries (like useRecoilState).

Of course every change has potential disadvantages, for example:

• useCosmosState is longer and more likely to cause the expression to be multiline (although this is helped a lot by the first change which allows passing the default value directly as the 2nd argument).

Feedback?

I'm pretty happy with both these changes and already made a tentative PR to see how the new API feels and you can tell by the diff it cleans up the code pretty nicely.

But I'd love to get your thoughts on this as well.

• What do you think of both changes, especially the naming part – the harderst part as we all know :).
• Should we rename useSelect to useCosmosSelect too even though its API won't change, just for consistency? Are these hooks getting too verbose? What if we add more specific ones in the future like use[Cosmos]Slider, use[Cosmos]Calendar, etc.?

Thanks!

[Kyr]

For the very first, I didnt thank's before to You for such huge efforts and jobs for this project, sorry, this one wonderfull and impressive.

Due to you request for comments that planed changes, may I propose:

1. Accepting default value as 2dn argument.
   May be seem as reasonable simplifying, but, sorry, I can not see any reason for reduce "verbose" is such way. I would like to propose to remain current API as is, but allow use primitive for second argument as "sugar" for the same API under the hood, e.g. useValue('answer', 42) could be easaly transform for actually usage into useValue('answer', {defaultValue: 42}).

just for example, my recent issue: the very simple component that accept single property as number in range 0..1 and display simple progress bar circle. Well, an existing useValue may accept changes with step 0.1, well enough, but not in my case, I would like to see 0.01. May be I mess in docs, but did I have a possibility to instruct input for exactly this prop, that it should be a range from/to with necessary step? It seems the original design, with so verbose 2nd argument could resolve this case, isnt it?

Moreover I suggest that could give really featured possibility to extends the ways how to present/display that value at the control panel, by hints, parameters, types or whatever else. Referring to (non-standard, but React's) useState does not seems very suitable, this one almost never meet real UI as labelled input with the same meaningful name.

2. Renaming useValue also seems not very reasonable, this name does not "pollute" any global space, namespace or something else, that just the very resoned name for hook from specific module. An any one could use use it in the very own way:

• import * as cosmos from 'react-cosmos/client'; - seems ok
• import { useValue as useCosmosValue } from 'react-cosmos/client'; - also ok
• import { useValue } from 'react-cosmos/client'; - ough, wait. but, there is nothing wrong!
• etc.
  Reason to rename just to avoid distinguish while using an object as the 2nd argument with field "defaultValue"... Hmm... Doubd.

[ovidiuch]

@Kyr Thanks for offering your thoughts.

I would like to propose to remain current API as is, but allow use primitive for second argument as "sugar" for the same API under the hood, e.g. useValue('answer', 42) could be easaly transform for actually usage into useValue('answer', {defaultValue: 42}).

Unless I'm missing something, I don't know how you can distinguish reliably whether the default value is passed as the 2nd argument (new way) or as a defaultValue key (old way) because the default value itself can be an object with have this shape: { defaultValue: ... }. Does this make sense?

An any one could use use it in the very own way:

Indeed you can alias an import ({ useValue as useCosmosValue }) or do (* as cosmos) but usually that requires manual work from the user. In general an IDE will auto import during auto complete the named import as it is exported in a library, and that is the use case I want to optimize for. If an API forces the user to alias their imports it's already at a disadvantage in my opinion.

I know this is a breaking change but I am willing to keep the useValue API backwards compatible indefinitely, as it is a minimal maintainance burden to expose it an alias. So I understand your concern.

I'm just trying to find the perfect API going forward as I think an elegant signature is very important even if it seems like a detail. I know it's frustrating when library authors introduce breaking changes willy nilly but like I said I would keep the old API backwards compatible and also it's trivial for users to upgrade to the new API. We can create a simple codemod to help with that.

So that being said, my question is, if we created this API today from scratch, what would it look like?

[birtles]

There's probably a way to work around the issue for TypeScript users such that when T extends { defaultValue: unknown } it assumes the old signature (and then in JS you'd check for an object with the defaultValue property when deciding how to interpret the value).

e.g.

type ShortcutFixtureStateData<T extends FixtureStateData> = T extends { defaultValue: any } : never : T;

// Overloads
useValue<T extends FixtureStateData>(inputName: string, defaultValue: ShortcutFixtureStateData<T>): [T, SetValue<T>];
useValue<T extends FixtureStateData>(inputName: string, options: Opts<T>): [T, SetValue<T>];

// Implementation
useValue<T extends FixtureStateData>(inputName: string, options: Opts<T> | T): [T, SetValue<T>] {
   // ... If `options` is an object with a `defaultValue` property, treat it as `Opts<T>` ...
}

That's probably the wrong syntax, but something of that nature might work.

Developers using JS only and using value objects that have a defaultValue could get confused, but that would be the only case I think.

But if that doesn't work, then I think your proposal sounds reasonable.

[ovidiuch]

If options is an object with a defaultValue property, treat it as Opts<T>

There is an edge case where the user's value is an object that has a defaultValue property and treating it like Opts<T> will cause unwanted behavior if they want to use the new shorthand syntax.

[birtles]

Right, the idea is to use TS to catch that edge case.

[ovidiuch]

OK, so in that case TS makes it clear that you're using the old syntax (Opts<T>) and you can solve it by doing something like useValue('myValue', { defaultValue: { defaultValue: 'foo' }}). But you may still want to use the new syntax even in that (albeit corner) case and I don't see how that can be achived while supporting both function signatures.

[birtles]

Yes, exactly. In the unlikely case you're using a type with a defaultValue property you have to use the old syntax (which I understand needs to remain for backwards compatibility anyway).

[ovidiuch]

After much thought and outside feedback I consolidated the fixture hooks into a concept called "Fixture Inputs" which is reflected in the updated docs. These are APIs that are meant to be used only inside fixtures, and they create interactive inputs in Cosmos' control panel that allow manipulating component data visually. The changes were published under version 6.1.0. All previous APIs are backwards compatible so there are no breaking changes.