feat: add todo-mobx-app example with MobX↔FASTElement bridge

[janechu]

Pull Request

📖 Description

Adds a new example, examples/todo-mobx-app/, that demonstrates how to bridge a MobX state store into FASTElement template bindings.

The example introduces two thin, application-scoped decorators that collapse the usual MobX-in-a-web-component boilerplate (a manual reaction() per observed field + manual Observable.notify() + manual disposer wiring in disconnectedCallback) down to two annotations:

• @mobxObservableProperty — marks a getter on a FASTElement subclass as one whose value comes from a MobX-tracked source. The getter is wrapped with Observable.track(this, key) so FAST treats it as a normal observable property in templates.
• @mobxObserver — class decorator that, on connectedCallback, sets up one MobX reaction per @mobxObservableProperty key. When MobX detects a change, the reaction calls Observable.notify(this, key) and FAST re-renders the dependent template bindings. Reactions are disposed on disconnectedCallback.

The bridge is uni-directional (MobX → FAST). Two-way input bindings (e.g. <todo-form>'s draft text) still use plain FAST @observable because that state is UI-local and not part of the MobX store.

The example app itself is a small Todo application with the typical features (add / toggle / remove / toggle-all / filter / clear-completed / item count) plus localStorage persistence via a mobx.autorun. State lives in a singleton TodoStore (makeAutoObservable) and is shared across all components, so no props need to be passed down — components read directly from the store through @mobxObservableProperty getters.

A DESIGN.md documents the bridge architecture, lifecycle ordering, the rationale for recycle: false on the <todo-list> repeat directive (otherwise FAST would rebind existing rows to new Todo objects without tearing down their MobX reactions, leaving stale subscriptions), and known gotchas around volatile getters and useDefineForClassFields.

This is an additive example only — no existing packages or public API are modified.

👩‍💻 Reviewer Notes

• The bridge code lives entirely under examples/todo-mobx-app/src/mobx-integration/. It is intentionally scoped to the example, not promoted to @microsoft/fast-element, so the team can evaluate the pattern before deciding whether to formalize it.
• Suggested smoke test: npm start -w @microsoft/fast-todo-mobx-app-example (port 9001), then add several todos, toggle some, switch filters, remove an item that was previously in the middle of the list, then toggle a row that took its place — this exercises the recycle: false path that ensures per-item MobX reactions are torn down and rebuilt when rows shift.
• examples/todo-mobx-app/tsconfig.json sets useDefineForClassFields: false and skipLibCheck: true. The first is required so MobX's makeAutoObservable(this) sees constructor-assigned fields (rather than Object.defineProperty-defined fields) and can convert them to observables. The second sidesteps a known gap in mobx@6.13.5's ObservableMap lib types vs. TypeScript's esnext Map interface.

📑 Test Plan

• npm run build (full repo): passes; the new package builds in ~1s via tsgo -p tsconfig.json && vite build and emits a ~131 KB www/ bundle.
• npm run biome:check on the new files: clean.
• npm run checkchange: no change files required (the example package is "private": true, so beachball skips it).
• Manual smoke test via Playwright against npm start -w @microsoft/fast-todo-mobx-app-example: add 3 todos through the form (verifies action propagation), verify list/stats text update reactively, toggle the middle row (verifies per-item bridge), switch the filter to "completed" (verifies computed view), remove an item and toggle the row that shifted into its slot (verifies recycle: false prevents stale reactions), reload the page (verifies localStorage persistence). All scenarios behaved as expected.
• No new unit tests added — the example follows the convention of the existing examples/todo-app/, which also has no tests of its own.

✅ Checklist

General

• I have included a change request file using $ npm run change
• I have added tests for my changes.
• I have tested my changes.
• I have updated the project documentation to reflect my changes.
• I have read the CONTRIBUTING documentation and followed the standards for this project.

⏭ Next Steps

If the team likes the pattern, a natural follow-up is to promote mobx-integration/ into its own optional adapter package (e.g. @microsoft/fast-element-mobx) so that other apps can consume the decorators without copy-pasting them.