ReDim - GitLite

KO | EN

gitlite — search

#database #redis #pytorch #llm #cross-platform #ios #chatgpt #ai-agents #sql #css

ReDim

(★ 11)

A stateful UI framework for Excel worksheets. Components, bindings, and fire-and-forget async over worksheet shapes, built on ROneCOne. No UserForms.

File Explorer

ZIP Download

- - analyze.yml
- - MissionControl.bas
  - Navigator.bas
  - PokeDex.bas
  - SnakeGame.bas
  - WidgetGallery.bas
- api.md
- async.md
- design.md
- ReDimHost.bas
- ReDimUI.cls
- - conftest.py
  - test_async.py
  - test_compile.py
  - test_core.py
  - test_demos.py
  - test_source_guards.py
  - test_spike.py
  - test_widgets.py
- - SpikeHost.bas
  - TestReDimAsync.bas
  - TestReDimCore.bas
  - TestReDimWidgets.bas
- build_workbooks.py
- check.py
- vba_sources.py
.gitignore
CHANGELOG.md
LICENSE
README.md
requirements-dev.txt

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

Command Glossary

Commands referenced in this DOCs, explained below.

🔍

`pip install`

View Details ▼

Install Python packages.

pip install {{package1 package2 ...}}

Install one or more packages:

pip install {{package1 package2 ...}} {{[-U|--upgrade]}}

Upgrade all specified packages to the latest version, installing any that are not already present:

pip install {{package}}=={{version}}

Install a specific version of a package:

🔍

`python`

View Details ▼

Python language interpreter.

python

Start a REPL (interactive shell):

python {{path/to/file.py}}

Execute a specific Python file:

python -i {{path/to/file.py}}

Execute a specific Python file and start a REPL:

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

A stateful UI framework for Excel worksheets. Build interactive, async-aware applications out of
worksheet shapes and form controls the way you would with a component framework on the web. No
UserForms, no ActiveX, no add-ins, no VBIDE access.

ReDim sits on top of [ROneCOne](https://github.com/WilliamSmithEdward/ROneCOne), which supplies
delegates, typed events, structured exceptions, and cooperative tasks. ReDim adds what ROneCOne's
one-file invariant cannot carry: the host loop (ROneCOne ADR 0007 anticipated exactly this), a
retained component model with diffed rendering, a state store with bindings, and an async engine
that keeps Excel responsive while work runs.

<p align="center">
  <a href="https://www.youtube.com/watch?v=2WAgLK5W5Fo">
    <img src="https://img.youtube.com/vi/2WAgLK5W5Fo/hqdefault.jpg"
         alt="ReDim: A UI Framework for Excel VBA - video" width="480">
  </a>
  <br>
  <em><a href="https://www.youtube.com/watch?v=2WAgLK5W5Fo">Watch: ReDim in action</a></em>
</p>

```vba
Dim app As ReDimUI

Set app = ReDimUI.Mount(Sheet1, "Dashboard")

app.Button("run").At("B2:C3").Text("Run Report").Primary.OnClickAsync "Demo.BuildReport"
app.ProgressBar("prg").At("B5:F5").BindValue "progress"
app.Label("status").At("B7:F7").BindText "statusMsg", "Status: {0}"

app.Render
```

Clicking Run disables the button, swaps its caption to busy text, runs `Demo.BuildReport` through
the pump, and restores the button when the work completes or fails. While a chunked job runs,
`app.SetState "progress", 40` moves the bar and `"statusMsg"` updates the label, all while the
user keeps working in the workbook.

## What it does

- **Components over shapes.** Button, Label, Card, ProgressBar, Spinner, Toggle, TickBox,
  RadioGroup, Stepper, SlideBar (press-drag), SelectBox, ComboBox (editable, filtering live
  as you type), TransferList (dual listbox with move buttons), CheckList (checkbox list
  with a tri-state select-all header), Image (embedded picture fills), TextInput, Toast,
  and a shapes-based modal overlay with Confirm - every
  control drawn from shapes and fully themed, with light and dark presets, no native form
  controls anywhere, no cells required (text fields float free of the grid via a keyboard
  focus layer, or anchor to a cell if you want one), and no dependencies beyond a stock
  Excel 365 install.
- **Stateful.** Each app owns a key-value store. `BindText`, `BindValue`, `BindVisible`, and
  `BindEnabled` re-render only what changed. `OnStateChanged` registers workbook procedures as
  state listeners. `WritesTo` flows control values back into state. The store is deliberately
  in-memory and session-scoped: persistence belongs to the host application, which can read
  the store, save it wherever fits (ROneCOne's JSON serializer is on board), and reseed on
  build with `SetStateDefault`, which never clobbers a value already in play.
- **Composable layout.** Anchor to ranges with `At`, to points with `AtRect`, or to other
  components with `Below` and `RightOf`. Render prunes shapes orphaned by renamed components,
  so iterating on app code never litters the sheet.
- **Windows.** Sheets as forms: `AsWindow` registers a window, `Navigate` shows one at a time
  (others go very-hidden), `NavigateBack` walks the stack, `OnShow` and `OnHide` fire like
  form lifecycle events, a button becomes a nav link with `NavigatesTo`, and `NavBar` renders
  window tabs with the active one highlighted. Background windows keep pumping.
  `ProtectSurface` turns an app sheet into a true application surface.
- **Genuinely async.** A SetTimer pump ticks whenever Excel idles and steps ROneCOne tasks
  without anyone blocking on `Await`. Fire-and-forget ops disable their controls, spin a spinner,
  and fire done, fail, or cancel handlers. HTTP, database, shell, and delay tasks overlap for
  real; CPU-bound VBA runs as chunked jobs inside a per-tick millisecond budget, or paced jobs
  for game loops and animations. Cancellation rides ROneCOne CancellationTokenSource.
- **Crash-railed.** The timer callback is a single guarded call that never lets an error escape,
  kills itself after repeated faults, stops when idle, records its timer id in a workbook name so
  orphans from VBA state loss are killed before re-arming, and tears down on workbook close.
- **Idempotent.** Re-running setup code adopts existing shapes instead of duplicating them, so an
  unhandled error that resets VBA state never leaves a broken sheet.

## Installation

1. Import `ROneCOne.cls` (from the ROneCOne release, 1.8.1 or later) into your macro-enabled
   workbook.
2. Import `src/ReDimUI.cls`.
3. Import `src/ReDimHost.bas`.

Three imports, no references, no registration. Windows x64 Microsoft 365 Excel, the same target
as ROneCOne.

## Demos

Built workbooks are attached to each
[release](https://github.com/WilliamSmithEdward/ReDim/releases). They are build artifacts
rather than sources, so they are not tracked here; `python tools/build_workbooks.py`
regenerates them into `demo/` from the VBA in `demo/vba/`. Open one with macros enabled
and it builds itself (each ships an `Auto_Open`); the entry macro rebuilds on demand.

| Workbook | Shows | Entry macro |
|---|---|---|
| `ReDim_Mission_Control.xlsm` | Three cancellable feeds with live progress, toasts, KPI cards, dark mode, confirm modal | `BuildMissionControl` |
| `ReDim_Widget_Gallery.xlsm` | Every component wired to a live state inspector | `BuildWidgetGallery` |
| `ReDim_Snake.xlsm` | A real game loop: paced pump job, arrow-key steering, score state, game-over modal | `BuildSnake` |
| `ReDim_Navigator.xlsm` | Sheets as forms: Navigate, back stack, lifecycle hooks | `BuildNavigator` |
| `ReDim_ReDex.xlsm` | The full-framework showcase: a living Pokedex on PokeAPI - async HTTP + JSON, sprite images, tweened stat bars, team building, custom theme with night mode | `BuildPokeDex` |

## Documentation

- [Getting started and API](docs/api.md)
- [The async engine](docs/async.md)
- [Architecture and design contract](docs/design.md)

## Development

VBA sources are plain files; workbooks are built artifacts.

```bash
pip install -r requirements-dev.txt
python tools/check.py          # pyvbaanalysis static gate, zero findings required
python tools/build_workbooks.py
python -m pytest tests/python  # live Excel suite via pyvbaharness
```

The live suite covers mount and adoption, dispatch and guards, bindings, batching, theming, the
async op lifecycle, jobs, cancellation, every widget, a real armed-timer end-to-end run, a VBA
compile gate for every shipped workbook, and smoke runs of all five demos.

It drives a real Excel instance, so it cannot run on hosted CI. Continuous integration runs
the static gate only, over the same sources plus the ROneCOne runtime; the live suite is a
local step before release.

## License

MIT