CodeClubs.org Support Code Clubs
Open source ยท MIT

velocity-react

The front-end half of velocity-python: forms, grids, navigation and sign-in, built from a description of your data, speaking a data contract in which the browser never writes SQL.

The back-end half

Overview

  • 0.2.14Current release
  • MITLicense
  • 18React
  • MUI 7Components
  • about 1,770Unit tests
  • pre-1.0Status

velocity-react is the front-end half of velocity-python: an application framework that turns a description of your data into a working application. Describe a table's fields once, and you get its form, its grid with search and filters, its place in the navigation and its permissions.

It speaks velocity-python's data contract directly. Tables are named, rows are plain objects with a sys_id, references end in _sys_id, and filters travel as structured data, so the browser never writes SQL.

The package is @velocity-framework/react. It ships as ES modules and CommonJS with TypeScript types. It is published to a private registry today; installation instructions for the public registry will follow its first public release.

Applications from metadata

Each table is described once, as a set of fields with widgets:

import { BooleanWidget, DateWidget, NumberWidget, TextWidget, system } from '@velocity-framework/react';

export const table = 'bare_items';
export const label = 'Bare Items';

export const fields = {
  ...system.fields,
  title: new TextWidget({ label: 'Title', searchable: true }),
  quantity: new NumberWidget({ label: 'Quantity' }),
  active: new BooleanWidget({ label: 'Active' }),
  due_date: new DateWidget({ label: 'Due Date' }),
};

From that description:

  • OmniField renders any field with the right widget, label and validation.
  • MetadataForm is a complete form page for any table: every field, then the system fields, then save buttons.
  • Widgets cover text, numbers, money, dates and times, email, phone, URLs, switches, colors, images, code, rich text, lookups and pointers. PointerField picks a related row with search instead of asking for an id.
  • Custom widgets register with registerWidgets, so an application can add its own without forking the framework.

Grids and lists

  • Server-side grids page, sort and filter in the database, so even a very large table loads one page at a time.
  • Facets show counts per value and narrow a grid with a click; right-click a cell to keep or hide only that value.
  • Aggregates show totals and averages in the footer, computed by the server.
  • Inline editing, column choice, saved views and export.
  • Bulk updates act on the filtered rows, and are refused if the result was cut short, so a bulk change never silently misses rows.
  • RecordNavigator is a pane for choosing one record from many: search, view chips with counts, grouping, sorting, pins, keyboard control and a quick switcher.

Filters without SQL

Filters are objects. The same grammar velocity-python uses on the server is built and checked in the browser:

{
  status: ["open", "held"],              // status IN ('open', 'held')
  ">=sys_created": "2026-01-01",         // sys_created >= '2026-01-01'
  "!%%name": "%test%",                   // name NOT ILIKE '%test%'
  "owner_sys_id>name": "Ada",            // the owner's name is 'Ada'
  notes: "@@EMPTY",                      // notes is null or empty
  "!archived_at": "@@NULL",              // archived_at IS NOT NULL
}

Builders combine filters (andWhere, orWhere, day ranges, grid filter models, search across fields), and checkWhere validates one before it is sent. The limits on search terms, fields and nesting match the server's exactly, and a check in the release gate replays sample requests through velocity-python's real boundary to prove the two still agree.

State and the API

  • One store. A single global store, configured once with the application's state and actions. Updates merge deeply, so a change to one part of the state never wipes its neighbors.
  • performApi sends every request. It handles the framework's own protocol first (background jobs, notifications, follow-up actions), then hands the result to the caller.
  • Guards. A circuit breaker, a rate limit and a loop detector stop a misbehaving screen from flooding the server. Responses that arrive after sign-out or a reset are discarded instead of updating a screen that has moved on.
  • Background jobs. Long work runs on the server's queue, and a progress portal follows it to the end.

Sign-in and sessions

  • Sign-in through Amazon Cognito, with protected layouts and routes.
  • Expired sessions are recognized for what they are. An expired sign-in can reach the browser looking like a network error; velocity-react tells the two apart, refreshes the session once without bothering anyone, and only then asks the person to sign in again.
  • Permissions. Routes and screens can require a permission, and roles, requests and effective access have their own administration screens.
  • Masquerade. When support signs in as a user to help them, a banner says so on every screen, for as long as it lasts.

Navigation and capabilities

The server tells the application which optional features are on for this site. Navigation hides what's off, deep links to it show a clear "not available" page, and until the answer arrives nothing is hidden, so an unknown never reads as off.

Building blocks

  • Tiles for a home screen: counters, watch lists, calendars and drop zones for files.
  • Forms built and filled in the browser, including public and portal pages.
  • Checklists, links, an asset browser and an operations dashboard that pairs with velocity-python's job tracking.
  • Calendars, notifications and modals that follow the same patterns everywhere.

Theming and branding

configureVelocity sets the product name, logo, support address, storage key prefix and more, and VelocityProvider overrides them for part of a page. Themes are MUI themes with a light and dark mode the person can choose. Fonts are registered by the application; the framework ships none, so every application uses fonts it is licensed for.

Security

  • The browser never builds SQL: filters are structured data, and SQL text is refused.
  • HTML from users is sanitized, and untrusted HTML, like an email, renders in a sandboxed frame with no scripts and a deny-all content policy.
  • Secrets and personal data are redacted before anything is logged or reported.
  • A publish gate scans every release for secrets, personal data, licensed files and client names before it can be published.

Testing and releases

  • Tests. About 1,770 tests in 195 files, run with Vitest in a simulated browser, in a fixed time zone that isn't UTC so date bugs can't hide.
  • The release gate runs lint, the tests, type tests, the server-contract replay and a build, then builds a bare example application with only the peer dependencies installed, to prove the framework carries no hidden application code.
  • Peer dependencies. React 18, MUI 7 with MUI X grids and date pickers, AWS Amplify 5, React Router 6 and a few small libraries. The application owns their versions.
  • Versions. Pre-1.0: a release may change behavior, and the changelog says when it does.