Repository navigation
Settle the public API before 2.0.0 - #369
Merged
Merged
Conversation
Its parameters defaulted to the values in force where it was called, so ColorPickerTheme(dimensions = ...) also fixed the colors and shapes of the MaterialTheme at that spot, and a MaterialTheme nested inside, such as a dark card, no longer reached the pickers under it. A parameter left null now passes on the enclosing value, or none, and each component resolves the default where it reads it.
ColorPickerDefaults.SliderThumb always drew at the 4 dp constant, so a wider thumbWidth, from a slider's dimensions or the theme, opened a wide gap in the track around a thin bar. It now takes its width from the dimensions in force, and each Material slider composes its thumb with its own dimensions in force, as the plane's default thumb already takes its diameter.
Its KDoc allowed reads from any thread, but the hue memory behind displayValue keeps the spaces it has seen in a plain map that a write on the main thread extends, so a read elsewhere can meet it half changed. Another thread takes the immutable value instead.
A const is copied into every caller when it compiles, so a library built on this one would keep 0.38 after a later release changed it, and the value could never come from the theme. As a val it is read where it is used.
It was composable though it reads no theme, only its own constants, so dimensions could not be kept in a top-level val or built in a view model. colors() and shapes() read MaterialTheme and stay composable.
A state saved before an app update can meet a space that was renamed, removed or redefined, and the saver's KDoc covered only the space that is not found. It now names every case that starts again from the initial value, and the one that does not: a space redefined under its old id reads the old components as new ones.
It was always 1.0 and nothing read it, so it promised an HDR parameter the library does not have, and once released it would bind whatever HDR design comes later to its name and meaning.
As enums, a grade or category added later would break every caller's exhaustive when, and crash one already compiled when it met the new value. Both can grow: Exactness has no grade yet for a profile-based space, and AnalogousCategory follows a CSS table that a later level may extend. HexAlpha and CssSyntax stay enums, since alpha has no fourth position in a hex string and CSS has no third syntax.
Subclassing ColorSpace already needs ExperimentalColorSpaceApi, but the parts a subclass describes itself with could be built freely, so adding a parameter to the ColorChannel constructor, or changing what a HueFamily id means, would have been a break. The factories and HueFamily's own families need no opt-in; ColorSpace.polar over a family of the app's own does.
ColorSlider and ColorPlane took onValueChangeFinished before enabled and as a nullable callback, like the basic slider and plane under them, while the channel and alpha sliders, the channel plane and every picker take enabled first and default the callback to {}. One order and one form means an argument moves between them unchanged.
The picker is the content BasicColorPickerDialogContent lays out, but it came second, before the optional parameters, so it could not be passed as a trailing lambda.
SliderLabel and SliderValueLabel were top-level functions without a modifier, the only visible components in the library to lack one, and apart from the default thumbs they sit beside in every slot a caller replaces.
Each was state.value = view.value under another name, one per space, so every space added later would have needed another. They came in as the writing half of the typed views; state.value = x and state[channel] = x now cover every write, and the views stay for reading.
…tates ColoringMode, a display option only sliders read, sat in codes.side.colorpicker.state beside ColorPickerState, while ColorPickerDialogState, a state, sat in codes.side.colorpicker.foundation among the components. Each now lives with its kind.
The KDoc said the display, but Okhsl is fitted to sRGB, which a Display P3 screen exceeds, and it strays out of sRGB just past pure blue, as README already says.
ColoringMode is the one set of options an app is likely to keep in saved UI state, as the sample does with rememberSaveable { mutableStateOf(mode) }. Android saves an enum there and cannot save a class, so the class form the other growable sets take would crash such an app on rotation, where an enum added to later only breaks a when at compile time. It stays an enum, and a coloring added later waits for a major release.
CONTRIBUTING gains the list of API conventions this and the neighbouring changes settled, so a later type, parameter or constant is decided the same way.
Sets of options stay enums, as ColoringMode does: an app can keep an enum in saved UI state, which Android cannot do with a class, and an option added later waits for a major release instead. This reverts 5aa781b, and the API conventions in CONTRIBUTING state the rule for every such set.
They were the last sets of options written as abstract classes with an object per option, where every other set in the library is an enum, as the API conventions in CONTRIBUTING require. Callers write PlaneRendering.Fast and EdgeSolver.Iterative as before, and toString still gives the option's name.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
API that the 2.0.0 tag would otherwise freeze.
Defects, each with a test that fails on master:
ColorPickerThemeinherits what it is not given.ColorPickerTheme(dimensions = …)also fixed the colors and shapes of theMaterialThemearound it, so aMaterialThemenested inside, such as a dark card, no longer reached the pickers under it.thumbWidthopened a wide gap in the track around the 4 dp bar. Each Material slider composes its thumb with its owndimensionsin force.Contracts:
ColorPickerStateis read and written on the main thread. Its KDoc allowed reads from any thread, but the hue memory behinddisplayValueis a plain map a write extends.ColorPickerState.Saversays what restores as the initial value: an unknown space, components the space now refuses, or another format, 1.x's included. A space redefined under its old id reads the old components as new ones.Surface:
PlaneRenderingandEdgeSolverwere abstract classes with an object per option, andColoringMode,Exactness,AnalogousCategory,HexAlphaandCssSyntaxstay enums. An app can keep an enum inrememberSaveable, where Android cannot save a class; an option added later waits for a major release.ColorChannel, aChannelKind.Hueor a newHueFamilyneedsExperimentalColorSpaceApi, as subclassingColorSpacealready did.RgbGamut.peakLuminanceis gone. It was always 1.0 and nothing read it.DisabledAlphaandDisabledSaturationare plainvals, andColorPickerDefaults.dimensions()is not composable.ColorSliderandColorPlanetakeenabledbeforeonValueChangeFinished, which is() -> Unit = {}on every slider, plane and picker, andBasicColorPickerDialogContenttakes itspickerlast.SliderLabelandSliderValueLabelareColorPickerDefaults.SliderLabelandSliderValueLabel, with amodifier.ColoringModeis incodes.side.colorpicker.foundation, andColorPickerDialogStateincodes.side.colorpicker.state.ColorPickerState.set(view)functions are gone;state.value = xandstate[channel] = xcover every write.CONTRIBUTING gains an API conventions section recording these choices, and CHANGELOG and the README migration table cover what a 1.x user sees.
apiCheck,checkNoMaterial,scripts/check-api-removals.sh, the 30 screenshot baselines and the Android, desktop and web samples pass.