colveor_ui 0.3.0

Themed Flutter UI toolkit with widgets, light/dark theming, go_router routing and base screen classes. The UI layer of Colveor.

Changelog

0.3.0

Breaking

• Dashboard: voDashboardControllerProvider, VoDashboardState and VoDashboardNavigationSource are removed, along with VoDashboardPane.configSignature, listConfigSignature, mergeRegistry and validateForSite.
• Dashboard: VoDashboardController is now a ChangeNotifier. Pass one as VoDashboard(controller:) to drive the dashboard from outside, or read it from context.dashboardScope.controller.
• Dashboard: VoDashboardScope's constructor changed. Its methods are unchanged: goTo, popShell, canPopShell, the drawer methods and handleBack.
• VoPhoneInput: validator, onSaved and onSubmitted receive the full E.164 number ([phone]) instead of the typed digits.
• VoSelectCountryField no longer calls onChanged with the starting country after its first frame, only when the user picks one. Its unused validator parameter is removed.

New

• VoGroupedView and VoGroupedView.grid: a list or grid of items split into groups. It supports:
  • group headers and footers, with optional sticky headers
  • sorting of groups and of items within a group
  • a slide-in animation for items as they appear (VoItemAnimation)
  • pagination (hasMore / onLoadMore) and pull to refresh
  • VoGroup.fromItems gives the same grouping without the widget.
• VoSelectCountryField, VoCountry and VoCountries are exported from widgets/inputs.dart.
  • VoCountries.search matches a country's name, ISO code or dial code.
  • VoCountries.byPhone now picks the longest matching dial code.
  • e164DialCode gives a dial code without separators (+1268 for +1-268).
• Dashboard: keepPanesAlive, onPaneReselected (called when the current pane is tapped again) and an optional controller.
• Documentation now covers every public widget and API, with parameter tables and samples checked against the code. New page: docs/extensions.md (context.vo, theme extensions, ref.setThemeMode, Color.darken/lighten).
• The example app now covers the whole package: theming, routing guards, storage, the dashboard, a sign-in page flow, and a showcase screen for each widget group.

Changes

• VoPinInput no longer depends on pinput; it draws its own boxes over a hidden text field. Its parameters are unchanged.
  • It supports SMS code autofill, accepts digits only, and calls onCompleted when the code is filled through a shared controller.
  • A new error clears the code, but clearing the error no longer wipes what the user typed since.
  • It no longer disposes a focusNode passed in by the caller, and a border set without focusBorderColor or errorBorderColor no longer crashes.
  • VoPinInputTheme is exported from widgets/inputs.dart, so the theme parameter can be used.
• Dependencies: go_router ^18.1.2 (needs Flutter 3.44 / Dart 3.12) and flutter_secure_storage ^11.2.0 (Android minSdk 24). Data saved with flutter_secure_storage versions before 10 can no longer be read; 0.2.0 already used 10.
• Dashboard panes stay alive after they are first shown, so tabs keep their scroll position and data. Set keepPanesAlive: false to rebuild a pane each time it is shown.
• Each dashboard has its own state. The nested ProviderScope never scoped the controller, so two dashboards shared one.
• The dashboard shows its current pane on the first frame instead of after a loading frame. loadingBuilder is deprecated and unused.
• Dashboard back closes an open drawer, then returns to the previously visited pane, then lets the route pop, which supports predictive back. History holds each pane once, so back doesn't replay every tab switch and never lands on a "not found" page.
• Changing the dashboard's initialPaneKey shows that pane and keeps history, instead of resetting the dashboard.
• VoDashboard(style:) now applies its spacerWidth to the dock.
• The default dashboard pane transition is a fade with a slight upward slide. Pass bodyAnimationBuilder to change it.
• The country picker lists each country by flag, name and dial code (it showed VoCountry(...) text). It can be searched, and lists favorites in the configured order.
• A picked country stays selected; it used to snap back to the first country on the next rebuild.
• VoPhoneInput parses the number for the selected country, so a national number with a trunk prefix (07700 900123) gives the right full number.
• VoPhoneInput applies validator and overlayType.
  • overlayType now defaults to bottomSheet. The old dialog default was ignored.
• VoPhoneInput uses the phone keyboard.
• VoPhoneInput applies these theme options: phoneHint, countryHint, overlayTitle, flagSize, flagShape and dividerWidth.
• A full phone initialValue no longer loses digits that repeat the dial code.
• Numbers such as +1268… select the right country.
• Overlay pickers close with Navigator.pop instead of GoRouter.pop, so they work without a GoRouter above them.
• VoSelectField no longer resets its selection whenever its parent rebuilds.
• New default look for overlays:
  • Bottom sheets have rounded top corners, a soft upward shadow, a visible drag handle and the theme's barrier color.
  • Titles use typography.titleMedium.
  • List rows are rounded and inset from the edge. The selected row is tinted with the primary color and gets a check; turn the check off with VoOverlayTileTheme(showSelectionIndicator: false).
  • Multi-select rows show a checkbox.
  • Every value can still be overridden in VoOverlayTheme and VoOverlayTileTheme. The new ...Of(context) methods return the resolved defaults.

Fixes

• Opening a bottom sheet with a ListTile in custom content no longer throws "ListTile background color or ink splashes may be invisible". The sheet background is now painted by a Material.
• Dialogs with list content no longer crash on intrinsic sizing.
• The bottom sheet drag handle now shows; it was hidden because the sheet controller wasn't attached on the first build.
• VoOverlayTile.subtitleBuilder works without also setting subtitle.
• Dialogs and modals no longer dispose a scrollController passed in by the caller.
• VoInputField applies VoFieldOptions.readOnly; read-only fields could be edited.
• VoPasswordField's visibility icon now shows and hides the password. It also applies the decoration passed to it, which was ignored.
• Divider and spacer panes have stable keys; rebuilds used to reset the dashboard's pane config.
• Divider panes no longer fill their background with the line color.
• Dashboard pane mistakes, such as a pane in the wrong list or duplicate keys, are reported by a debug assert that names the constructor to use. They used to throw an ArgumentError in release builds.

0.2.0

• Added VoStorage (package:colveor_ui/storage.dart), a key-value store backed by the secure storage colveor_ui already depends on, so apps and packages built on it don't need their own storage dependency.
• The theme mode is saved through VoStorage under the same theme_mode key, so saved themes still load.
• Documentation now lives in doc/ and is published at colveor.dev. The README links to it.

0.1.0

Breaking

• Removed VoWidget and VoConsumerWidget. They stored the BuildContext on the widget instance, so a widget mounted in more than one place (any reused const widget) could read another copy's theme or a closed dialog's context from callbacks. This only showed up in profile and release builds. Extend StatelessWidget / ConsumerWidget and use context.vo for the helpers.
• context.voToolkit is now context.vo.
• VoContextMixin.setToolkitContext is removed; voContext is now an abstract getter.

Changes

• ColveorApp takes designSize, minTextAdapt and splitScreenMode. The design size used to be fixed at 360×690, which is still the default.
• Country data now loads the first time VoPhoneInput or VoSelectCountryField is built, not in VoBootstrap.initialize. Pass preloadCountries: true to load it at startup.
• Fixed the integrated VoPhoneInput country label, which defaulted to "Country22".
• VoState and VoConsumerState are unchanged and still expose the helpers as members.
• context.colorScheme added to the theme extension.
• Fixed VoOverlayView's back button, which could pop using another copy's context.
• README: install from pub.dev.

0.0.1

• Initial release, split out of colveor as a standalone UI layer.
• Widgets: buttons, inputs (text, phone, PIN, password, search, select), display, layout, overlays, feedback and toasts, page flows, dashboard.
• Theming with light/dark mode and overridable colors, sizes, typography and component themes.
• go_router routing configured through VoRoutingConfig with redirect and init callbacks.
• ColveorApp, ColveorRef, VoBootstrap, and VoWidget / VoState / VoConsumerWidget / VoConsumerState base classes.
• Utilities: VoLogger, VoValidators, and date, number, phone and text formatters.