v13.0.0

🍀Lucky v13 brings with it a number of enhancements for forms and validation, grouped column support in the core Grid API, a fully wrapped MultiSelect component, decorator syntax adjustments, and a number of other fixes and enhancements.

It also includes contributions from new ExHI team members Arjun and Brendan. 🎉

💥 Breaking Changes

• The core @HoistComponent, @HoistService, and @HoistModel decorators are no longer parameterized, meaning that trailing () should be removed after each usage. (#586)
• The little-used hoistComponentFactory() method was also removed as a further simplification (#587).
• The HoistField superclass has been renamed to HoistInput and the various desktop form control components have been renamed to match (55afb8f). Apps using these components (which will likely be most apps) will need to adapt to the new names.
  • This was done to better distinguish between the input components and the upgraded Field concept on model classes (see below).

🎁 New Features

⭐️ Forms and Fields have been a major focus of attention, with support for structured data fields added to Models via the @FieldSupport and @field() decorators.

• Models annotated with @FieldSupport can decorate member properties with @field(), making those properties observable and settable (with a generated setXXX() method).
• The @field() decorators themselves can be passed an optional display label string as well as zero or more validation rules to define required constraints on the value of the field.
• A set of predefined constraints is provided within the toolkit within the /field/ package.
• Models using FieldSupport should be sure to call the initFields() method installed by the decorator within their constructor. This method can be called without arguments to generally initialize the field system, or it can be passed an object of field names to initial/default values, which will set those values on the model class properties and provide change/dirty detection and the ability to "reset" a form.
• A new FormField UI component can be used to wrap input components within a form. The FormField wrapper can accept the source model and field name, and will apply those to its child input. It leverages the Field model to automatically display a label, indicate required fields, and print validation error messages. This new component should be the building-block for most non-trivial forms within an application.

Other enhancements include:

• Grid columns can be grouped, with support for grouping added to the grid state management system, column chooser, and export manager (#565). To define a column group, nest column definitions passed to GridModel.columns within a wrapper object of the form {headerName: 'My group', children: [...]}.

🐞 Bug Fixes

📚 Libraries

Commit Log

v12.1.2

🐞 Bug Fixes

• Fix casing on functions generated by @settable decorator (35c7daa).

Commit Log

v12.1.1

🐞 Bug Fixes

• Avoid passing unknown HoistField component props down to Blueprint select/checkbox controls.

📚 Libraries

• Rollback update of @blueprintjs/select package 3.1.0 -> 3.0.0 - this included breaking API changes and will be revisited in #558.

Commit Log

v12.1.0

🎁 New Features

• New @bindable and @settable decorators added for MobX support. Decorating a class member property with @bindable makes it a MobX @observable and auto-generates a setter method on the class wrapped in a MobX @action.
• A fontAwesomeIcon element factory is exported for use with other FA icons not enumerated by the Icon class.
• CSS variables added to control desktop Blueprint form control margins. These remain defaulted to zero, but now within CSS with support for variable overrides. A Blueprint library update also brought some changes to certain field-related alignment and style properties. Review any form controls within apps to ensure they remain aligned as desired (8275719 and df667b7).

🪲 Bug Fixes

• Grid cells are fully refreshed on a data update, ensuring cell renderers that rely on data other than their primary display field are updated (#550).
• Grid auto-sizing is run after a data update, ensuring flex columns resize to adjust for possible scrollbar visibility changes (#553).
• Dropdown fields can be instantiated with fewer required properties set (#541).

📚 Libraries

• Blueprint 3.0.1 -> 3.4.0
• FontAwesome 5.2.0 -> 5.3.0
• CodeMirror 5.39.2 -> 5.40.0
• MobX 5.0.3 -> 5.1.0
• router5 6.3.0 -> 6.4.2
• React 16.4.1 -> 16.4.2

Commit Log

v12.0.0

Hoist React v12 is a relatively large release, with multiple refactorings around grid columns, elemFactory support, classNames, and a re-organization of classes and exports within utils.

💥 Breaking Changes

⭐️ Grid Columns

A new Column class describes a top-level API for columns and their supported options and is intended to be a cross-platform layer on top of ag-Grid and TBD mobile grid implementations.

• The desktop GridModel class now accepts a collection of Column configuration objects to define its available columns.
• Columns may be configured with flex: true to cause them to stretch all available horizontal space within a grid, sharing it equally with any other flex columns. However note that this should be used sparingly, as flex columns have some deliberate limitations to ensure stable and consistent behavior. Most noticeably, they cannot be resized directly by users. Often, a best practice will be to insert an emptyFlexCol configuration as the last column in a grid - this will avoid messy-looking gaps in the layout while not requiring a data-driven column be flexed.
• User customizations to column widths are now saved if the GridModel has been configured with a stateModel key or model instance - see GridStateModel.
• Columns accept a renderer config to format text or HTML-based output. This is a callback that is provided the value, the row-level record, and a metadata object with the column's colId. An elementRenderer config is also available for cells that should render a Component.
• An agOptions config key continues to provide a way to pass arbitrary options to the underlying ag-Grid instance (for desktop implementations). This is considered an "escape hatch" and should be used with care, but can provide a bridge to required ag-Grid features as the Hoist-level API continues to develop.
• The "factory pattern" for Column templates / defaults has been removed, replaced by a simpler approach that recommends exporting simple configuration partials and spreading them into instance-specific column configs. See the Admin app for some examples of this pattern.
• See 0798f6b for primary commit.

⭐️ Element Factory, LayoutSupport, BaseClassName

Hoist provides core support for creating components via a factory pattern, powered by the elem() and elemFactory() methods. This approach remains the recommended way to instantiate component elements, but was simplified and streamlined.

• The rarely used itemSpec argument was removed (this previously applied defaults to child items).
• Developers can now also use JSX to instantiate all Hoist-provided components while still taking advantage of auto-handling for layout-related properties provided by the [LayoutSupport mixin].
  • HoistComponents should now spread ...this.getLayoutProps() into their outermost rendered child to enable promotion of layout properties.
• All HoistComponents can now specify a baseClassName on their component class and should pass className: this.getClassName() down to their outermost rendered child. This allows components to cleanly layer on a base CSS class name with any instance-specific classes.
• See 8342d38 for primary commit.

⭐️ Panel resizing / collapsing

The Panel component now takes a sizingModel prop to control and encapsulate newly built-in resizing and collapsing behavior (#534).

• See the PanelSizingModel class for configurable details, including continued support for saving sizing / collapsed state as a user preference.
• The standalone Resizable component was removed in favor of the improved support built into Panel directly.

Other

• Two promise-related models have been combined into a new, more powerful PendingTaskModel, and the LoadMask component has been removed and consolidated into Mask (d00a5c6).
  • Panel now exposes a single mask prop that can take either a configured mask element or a simple boolean to display/remove a default mask.
• Classes within the utils package have been re-organized into more standardized and scalable namespaces. Imports of these classes will need to be adjusted.

🎁 New Features

• The desktop Grid component now offers a compact mode with configurable styling to display significantly more data with reduced padding and font sizes.
• The top-level AppBar refresh button now provides a default implementation, calling a new abstract requestRefresh() method on HoistApp.
• The grid column chooser can now be configured to display its column groups as initially collapsed, for especially large collections of columns.
• A new XH.restoreDefaultsAsync() method provides a centralized way to wipe out user-specific preferences or customizations (#508).
• Additional Blueprint MultiSelect, Tag, and FormGroup controls re-exported.

🐞 Bug Fixes

• Some components were unintentionally not exporting their Component class directly, blocking JSX usage. All components now export their class.
• Multiple fixes to DayField (#531).
• JsonField now responds properly when switching from light to dark theme (#507).
• Context menus properly filter out duplicated separators (#518).

Commit Log

v11.0.0

💥 Breaking Changes

• Blueprint has been upgraded to the latest 3.x release. The primary breaking change here is the renaming of all pt- CSS classes to use a new bp3- prefix. Any in-app usages of the BP selectors will need to be updated. See the Blueprint "What's New" page.
• FontAwesome has been upgraded to the latest 5.2 release. Only the icons enumerated in the Hoist Icon class are now registered via the FA library.add() method for inclusion in bundled code, resulting in a significant reduction in bundle size. Apps wishing to use other FA icons not included by Hoist must import and register them - see the FA React Readme for details.
• The mobx-decorators dependency has been removed due to lack of official support for the latest MobX update, as well as limited usage within the toolkit. This package was primarily providing the optional @setter decorator, which should now be replaced as needed by dedicated @action setter methods (19cbf86).

🎁 Enhancements

• HoistComponent now provides a getClassNames() method that will merge any baseCls CSS class names specified on the component with any instance-specific classes passed in via props (#252).
  • Components that wish to declare and support a baseCls should use this method to generate and apply a combined list of classes to their outermost rendered elements (e.g. this usage within Grid).
  • Base class names have been added for relevant Hoist-provided components - e.g. .xh-panel and .xh-grid. These will be appended to any instance class names specified within applications and be available as public CSS selectors.
• Relevant HoistField components support inline leftIcon and rightElement props. DayField adds support for minDay / maxDay props.
• Styling for the built-in ag-Grid loading overlay has been simplified and improved (#401).
• Grid column definitions can now specify an excludeFromExport config to drop them from server-generated Excel/CSV exports (#485).

🐞 Bug Fixes

• Grid data loading and selection reactions have been hardened and better coordinated to prevent throwing when attempting to set a selection before data has been loaded (#484).

📚 Libraries

• Blueprint 2.x -> 3.x
• FontAwesome 5.0.x -> 5.2.x
• CodeMirror 5.37.0 -> 5.39.2
• router5 6.2.4 -> 6.3.0

Commit Log

v10.0.1

🐞 Bug Fixes

• Grid export context menu token now defaults to server-side 'exportExcel' export.
  • Specify the exportLocal token to return a menu item for local ag-Grid export.
• Columns with field === null skipped for server-side export (considered spacer / structural columns).

v10.0.0

💥 Breaking Changes

• Access to the router API has changed with the XH global now exposing router and routerState properties and a navigate() method directly.
• ToastManager has been deprecated. Use XH.toast instead.
• Message is no longer a public class (and its API has changed). Use XH.message/confirm/alert instead.
• Export API has changed. The Built-in grid export now uses more powerful server-side support. To continue to use local AG based export, call method GridModel.localExport(). Built-in export needs to be enabled with the new property on GridModel.enableExport. See GridModel for more details.

🎁 Enhancements

• New Mobile controls and AppContainer provided services (impersonation, about, and version bars).
• Full-featured server-side Excel export for grids.

🐞 Bug Fixes

• Prevent automatic zooming upon input focus on mobile devices (#476).
• Clear the selection when showing the context menu for a record which is not already selected (#469).
• Fix to make lockout script readable by Compatibility Mode down to IE5.

📚 Libraries

• MobX 4.2.x -> 5.0.x

Commit Log

v9.0.0

💥 Breaking Changes

• Hoist-provided mixins (decorators) have been refactored to be more granular and have been broken out of HoistComponent.
  • New discrete mixins now exist for LayoutSupport and ContextMenuSupport - these should be added directly to components that require the functionality they add for auto-handling of layout-related props and support for showing right-click menus. The corresponding options on HoistComponent that used to enable them have been removed.
  • For consistency, we have also renamed EventTarget -> EventSupport and Reactive -> ReactiveSupport mixins. These both continue to be auto-applied to HoistModel and HoistService classes, and ReactiveSupport enabled by default in HoistComponent.
• The Context menu API has changed. The ContextMenuSupport mixin now specifies an abstract getContextMenuItems() method for component implementation (replacing the previous renderContextMenu() method). See the new ContextMenuItem class for what these items support, as well as several static default items that can be used.
  • The top-level AppContainer no longer provides a default context menu, instead allowing the browser's own context menu to show unless an app / component author has implemented custom context-menu handling at any level of their component hierarchy.

🐞 Bug Fixes

• TabContainer active tab can become out of sync with the router state (#451)
  • ⚠️ Note this also involved a change to the TabContainerModel API - activateTab() is now the public method to set the active tab and ensure both the tab and the route land in the correct state.
• Remove unintended focused cell borders that came back with the prior ag-Grid upgrade.

Commit Log

v8.0.0

Hoist React v8 brings a big set of improvements and fixes, some API and package re-organizations, and ag-Grid upgrade, and more. 🚀

💥 Breaking Changes

• Component package directories have been re-organized to provide better symmetry between pre-existing "desktop" components and a new set of mobile-first component. Current desktop applications should replace imports from @xh/hoist/cmp/xxx with @xh/hoist/desktop/cmp/xxx.
  • Important exceptions include several classes within @xh/hoist/cmp/layout/, which remain cross-platform.
  • Panel and Resizable components have moved to their own packages in @xh/hoist/desktop/cmp/panel and @xh/hoist/desktop/cmp/resizable.
• Multiple changes and improvements made to tab-related APIs and components.
  • The TabContainerModel constructor API has changed, notably children -> tabs, useRoutes -> route (to specify a starting route as a string) and switcherPosition has moved from a model config to a prop on the TabContainer component.
  • TabPane and TabPaneModel have been renamed Tab and TabModel, respectively, with several related renames.
• Application entry-point classes decorated with @HoistApp must implement the new getter method containerClass() to specify the platform specific component used to wrap the app's componentClass.
  • This will typically be @xh/hoist/[desktop|mobile]/AppContainer depending on platform.

🎁 New Features

• Tab-related APIs re-worked and improved, including streamlined support for routing, a new tabRenderMode config on TabContainerModel, and better naming throughout.
• Ag-grid updated to latest v18.x - now using native flex for overall grid layout and sizing controls, along with multiple other vendor improvements.
• Additional XH API methods exposed for control of / integration with Router5.
• The core @HoistComponent decorated now installs a new isDisplayed getter to report on component visibility, taking into account the visibility of its ancestors in the component tree.
• Mobile and Desktop app package / component structure made more symmetrical (#444).
• Initial versions of multiple new mobile components added to the toolkit.
• Support added for IdleService - automatic app suspension on inactivity (#427).
• Hoist wrapper added for the low-level Blueprint button component - provides future hooks into button customizations and avoids direct BP import (#406).
• Built-in support for collecting user feedback via a dedicated dialog, convenient XH methods and default appBar button (#379).
• New XH.isDevelopmentMode constant added, true when running in local Webpack dev-server mode.
• CSS variables have been added to customize and standardize the Blueprint "intent" based styling, with defaults adjusted to be less distracting (#420).

🐞 Bug Fixes

• Preference-related events have been standardized and bugs resolved related to pushAsync() and the prefChange event (ee93290).
• Admin log viewer auto-refreshes in tail-mode (#330).
• Distracting grid "loading" overlay removed (#401).
• Clipboard button ("click-to-copy" functionality) restored (#442).

Commit Log