Skip to content
jameymcelveenPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

12 Commits

Folders and files

Repository files navigation

jsctrls

Data-aware React controls, inspired by Delphi.

CI Status: early development License: MIT React 18 TypeScript strict Java 21 Spring Boot 3 Docker Compose

Back in the Delphi days, you dropped a data source on a form, pointed a grid and a few edit boxes at it, and the controls just knew how to read, edit, post and cancel. Most React apps rebuild that plumbing by hand in every screen.

jsctrls brings the idea forward. It is inspired by Delphi's VCL, not a copy: modern React and TypeScript idioms win wherever the two disagree.

The idea: four layers, one job each

Layer Delphi role it borrows Job Knows about
Connector TConnection / TRESTClient Talk to a server with CRUD HTTP only, no state
DataSet TDataSet Rows, cursor, edit state, loading, errors The connector, not React
Binding TDataSource Let React subscribe to a DataSet The DataSet and React
Controls DB-aware controls Show and edit data Only the binding

The one rule: a control never talks to a server. Controls go through the binding, and the DataSet decides when to call the connector. Swap the connector and nothing above it changes.

interface Connector<T, K = string> {
  list(query?: Query): Promise<T[]>;
  get(id: K): Promise<T>;
  create(item: Omit<T, "id">): Promise<T>;
  update(id: K, item: Partial<T>): Promise<T>;
  remove(id: K): Promise<void>;
}

The DataSet is plain TypeScript with no React inside: a small state machine (browse, inserting, editing, posting, deleting, error) with a cursor, post and cancel, and errors that never lose what the user typed. React binds to it through useSyncExternalStore.

Hello world

Delphi's classic first program, an edit box, a list box and an Add button, plus Delete:

const names = createDataSet<{ id: string; name: string }>({
  connector: restConnector({ baseUrl: "/api", resource: "names" }),
});

function App() {
  const [text, setText] = useState("");
  const ds = useDataSet(names);
  useEffect(() => { names.open(); }, []);
  return (
    <>
      <TextInput value={text} onChange={setText} />
      <Button disabled={!text.trim() || ds.busy}
              onClick={async () => { await names.append({ name: text }); setText(""); }}>
        Add
      </Button>
      <Button disabled={ds.current == null || ds.busy} onClick={() => names.delete()}>
        Delete
      </Button>
      <ListBox dataSet={names} display="name" />
    </>
  );
}

Repository layout

packages/jsctrls   the library: connectors, DataSet, binding, controls
apps/hello         the hello world app
server/java        demo REST API in Java 21 + Spring Boot 3 (the default)
server/dotnet      the same API in .NET 10
server/go          placeholder
server/node        placeholder
specs              done and draft specs, with feature files for the done ones
docker-compose.yml runs one API and the app. SERVER=java by default

The demo servers implement one names API. The Java one is the default: records for DTOs, constructor injection, Bean Validation, ProblemDetail errors and MockMvc tests. The .NET server is the other implementation. Go and Node are folders only.

Getting started

make help                  # list every target
make up                    # Java API + app on http://localhost:8080
make up SERVER=dotnet      # same app, .NET API
make dev                   # Spring Boot on :8081 + Vite, no Docker
make dev SERVER=dotnet     # .NET API on :8081 + Vite
make check                 # lint, typecheck, web tests, Java tests, .NET tests

SERVER accepts java, dotnet, go, or node. Go and Node stop with an error until they exist. make test-api and make build use the same switch. make test always runs both implemented APIs.

Status

The hello world is in place: an edit box, a list, Add, and Delete, talking to the Spring Boot names API.

  • Workspace scaffold, Makefile, lint and test setup
  • Spring Boot demo API with MockMvc tests
  • memoryConnector and restConnector
  • DataSet state machine, test-first
  • useDataSet binding
  • TextInput, Button, ListBox
  • Hello world, end to end, with Docker Compose

What's next

Done and draft work is listed in specs/.

  • Bound DataField, DataNavigator and DataGrid
  • Optimistic posts as an option
  • A Contacts example app
  • Further out: a drag-and-drop form designer, the way Delphi did it

Author

Built by Jamey McElveen, a principal software architect who has been building components since the Delphi days.

Copyright (c) 2026 Jamey McElveen

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages