wq.app 2.0 alpha

wq.app 2.0 alpha is a preview of the next version of wq.app, as part of the wq 2.0 alpha release. The default interface has been upgraded to MUI v5 with MapLibre integration, and support for legacy jQuery Mobile & Leaflet projects has been completely removed.

All changes by @sheppard.

Packaging & Ecosystem

A number of changes significantly improve integration with npm and other build tools, as well as Node itself.

• All third-party packages have been updated to latest package versions. In particular, @material-ui/core (v4) has been upgraded to the latest @mui/material (v5). (9f9515c, b468228, 28e79ce, 4568600, 6453db3, 84eb5b3, 2c635b4, 79b28cf, 2cd8832).

• All imports (including package-internal imports) are now ESM-compliant with .js extensions. It is now possible to execute wq.app directly from Node. (wq/wq#58, 34f07d9, c47b145)

• @wq/material has been split into separate implementation packages, @wq/material-web and @wq/material-native. @wq/material automatically re-exports from @wq/material-web when running in e.g. Create React App, and from @wq/material-native when running in e.g. Expo. This separation makes it possible to correctly specify the necessary dependencies for each implementation, while remaining compatible with the latest NPM package specifications. Similarly, @wq/map-gl has been split into separate @wq/map-gl-web and @wq/map-gl-native packages; see below for details. (wq/wq#59, b21881a, 984d97a).

• Support for wq 1.2-style AMD projects has been completely removed, as well as the @wq/jquery-mobile and @wq/leaflet npm packages. These are maintained in the 1.3 branch if needed. (#111, eb238c0, 1bbbe37, a6dc7bf, 60cd668)

• Several improvements have been made to the wheel generation process. (0225fc2, ad137bf, b2c946f)

wq.js improvements

The pre-built wq.js script included in wq.app (and on npm) now exports several additional MUI components for use in plugins built with @wq/rollup-plugin. Since these imports are processed at runtime, wq.js automatically warns if an export is not found (44ade26, c39aa11, 5f018b3).

For example, @wq/rollup-plugin will transform this:

import { FakeComponent } from "@mui/material";

Into this:

import { modules } from "./wq.js";
const { FakeComponent } = modules["@mui/material"];

When this code is executed in the browser, wq.js will warn that it doesn't have that component (and return an empty component instead, to avoid completely breaking the UI.) Note that some valid @mui/material components are missing from wq.js and will return the same error - see modules.js for what's included.

Also note that the mapping engine is now shipped as a separate .js file and not baked into wq.js (31ad8b8, see below).

MapLibre Integration

Since MapBox is no longer open source, it has been replaced with MapLibre in the default wq.app configuration for both web and native (#128).

• @wq/map-gl-web now exports a setEngine() function that accepts the library object to use. When installing @wq/map-gl and @wq/map-gl-web from npm, this must be called explicitly. When installing wq.app from PyPI, the pre-built wq.js file already sets this to the output of ./maplibre-gl.js, which is deployed in the same directory as wq.js (31ad8b8, b468228).
• The React integration has been switched from react-mapbox-gl to react-map-gl. The latter supports swapping the map engine for MapLibre, and also has built-in support for reusing map instances when components are replaced via navigation state changes. The StickyMap component and associated offscreen component hacks have been removed in favor of this built-in support. (31ad8b8, 2cc0f40, 6215aa9).
• @wq/map-gl-native leverages @rnmapbox/maps, which defaults to MapLibre Native by default. See the @rnmapbox/maps documentation for information on how to override the default. (0deeb88)

New & Updated Components

Several new components have been added to the registry to provide a more complete UI out of the box.

New Map Components

AutoMap now supports displaying a MUI-styled toolbar with radio buttons for switching the basemap, switches for toggling overlay layers, and a simple legend for each overlay. This support required the addition of several new component types, as shown below (0da45cd, 361ea6c, c39aa11, 2da4718).

Component	Description
MapProvider	Top level component providing a context for referencing a nearby map object
useMapInstance	This hook existed before, but it now finds the map through the MapProvider context instead of the @wq/map redux state.
MapLayers	Virtual node wrapping all AutoBasemap and AutoOverlay nodes. The default is just a Fragment
MapContainer	Layout node that contains both the Map component and the new MapToolbar MapToolbar
SidePanel	Lightweight responsive drawer for embedding in e.g. map views.
CheckboxButton	Checkbox for cases that don't require a form input
RadioButton	Radio button for cases that don't require a form input
Switch	Switch component
Legend	Renders the legend for an individual overlay. (Note that MapToolbar was named Legend in wq.app 1.3. )
LegendIcon	Legend Icon component

The conceptual component tree for a typical AutoMap layout is now as follows:

<MapProvider>
  <AutoMap>
    <MapContainer>
      <MapToolbar>
        <BasemapToggle>
          <RadioButton />
        </BasemapToggle>
        <OverlayToggle>
          <Switch />
          <Legend>
            <LegendIcon />
          </Legend>
        </OverlayToggle>
      </MapToolbar>
      <Map>
        <MapInteraction />
        <MapAutoZoom />
        <MapIdentify />
        <MapLayers>
          <AutoBasemap>
            <Tile />
          </AutoBasemap>
          <AutoOverlay>
            <Geojson />
          </AutoOverlay>
        </MapLayers>
        <Highlight />
      </Map>
    </MapContainer>
  </AutoMap>
  <HighlightPopup />
</MapProvider>

These components can customized or disabled through configuration, through the component registry, and (in the case of MapToolbar) through props provided to <AutoMap/>. Set <AutoMap toolbar={<CustomToolbar/>} /> to override the default, or <AutoMap toolbar={false} /> to disable it.

New Layout Components

The default layout has been improved for both desktop and mobile devices, through the addition of a number of components.

Component	Description	Commit
Logo	Site logo shown in app bar. Set config.logo to an image path, or overrride the component.	3a51fe7
NavMenu	Responsive site navigation menu. On small screens this will appear via NavMenuPopup, while larger screens will use NavMenuFixed. NavMenu itself is registered as a view component that is the same as Index by default but can be overridden.	d68754c, 7e9e157
TabGroup	Based on @mui/materia's Tabs, but automatically renders the content for the selected tab. Used in @wq/map's updated DefaultList and DefaultDetail to support a tabbed layout on small screens.	461add6
TabItem	Based on @mui/material's Tab, but with support for @wq/react's icon registry. Accepts children which are conditionally rendered by TabGroup	461add6
BottomNavigation	@mui/material's BottomNavigation	461add6
BottomNavigationAction	Based on @mui/material's BottomNavigationAction, but with support for @wq/react's icon registry.	461add6
TablePagination	@mui/material's TableNavigation	cfd1993
TableContainer	@mui/material's TableContainer	cfd1993

Updated Components

Component	Description	Commit
Accordion	Renamed from ExpansionPanel	9f9515c
PropertyTable	Now renders nested fieldsets and arrays as sub-tables instead of JSON	d27b71d
OutboxList	Fix flex layout	7b1f09a
IconButton	Throw specific error if icon is missing, rather than waiting for React to fail	47cb370
Select	Improve formik-mui integration & also support native <select>	c39aa11, ffd813e, 727231b
DateTime	Remove custom date picker library in favor of <input type="datetime-local">	7b1f09a, 969f2fd

Data Model & Configration

• Most foreign key logic has moved out of the legacy context generator into components and @wq/model capabilities. In particular, ForeignKey is now a separate input type that renders as Select after directly querying the ORM for available choices. (#75, ffd813e, b6d2877, a88f426, 8090833)
• The mostly redundant wq_config object led to confusion, and has been removed (wq/wq#54, b453065)
• Route templates (i.e. view components) can be specifed through configuration (d1c85ca)
• page.defaults now works for fields nested under fieldsets (49b1af2)