diff --git a/website/src/components/Playground/README.md b/website/src/components/Playground/README.md index f30552e59c61..dd60e4a548a8 100644 --- a/website/src/components/Playground/README.md +++ b/website/src/components/Playground/README.md @@ -30,11 +30,13 @@ editor/ code model + editor UI EditorSurface.tsx headers, file tabs, collapse state, per-file TextEditTab StaticEditor.tsx SSR/crawler/loading markup (Prism, not editable) InteractiveEditor.tsx client-only: Monaco, or editable react-live on mobile/bots + declarations.ts top-level names each document declares (managers' reload, Store links) + openCode.ts CodeOpenerContext: what the Store can open in the code monaco/ everything Monaco-specific setup.ts side-effect init: CDN loader, hints, compiler options, theme, types typeLibs.ts raw .d.ts chunks from editor-types/ → addExtraLib navigation.ts import completions - useDefinitionOpener.ts cross-tab go-to-definition into this editor + useDefinitionOpener.ts cross-tab go-to-definition, and `reveal` for Store links, into this editor modelPath.ts `//` model URI scheme models.ts creates a surface's models together so cross-tab imports type-check preloadManifest.ts GENERATED by website/scripts/generateMonacoPreloads.cjs @@ -43,6 +45,9 @@ preview/ live execution (loaded lazily, never on the server) LivePreview.tsx react-live LiveProvider with scope + transformCode Preview.tsx DataProvider + MockResolver(fixtures) + Store inspector StoreToggle.tsx Store toggles + open state + store/ Store inspector: StorePanel owns navigation (nav.tsx), actionLog.ts + logs dispatches, actionGroups.ts groups them, attribution.ts + says which manager sent or handled each (Pipeline.tsx, ManagerName.tsx) autorun/ the `autoRun` demo player (see Auto-run) ... editor-types/ .d.ts bundles fed to Monaco (raw-loader) @@ -178,115 +183,50 @@ DesignSystem/ components injected into preview scope store (see Reset) starts a new history, a store the retry restores continues its own, and the panel shows only the current one. An action's chips open the store as that action left it (see `Moment` in `preview/store/nav.tsx`). -- The Store inspector navigates by two coordinates (see - `preview/store/nav.tsx`, both owned by `StorePanel`): the **moment** (the - action shown, or live; `NavStateContext` carries it down, with where a - step back or on lands (`earlier`, `later`), and `set` and - `show(seq)` back up: `show` also opens that action in the Action tab) and the **subject** (a - stack of levels over the store: a table, a record, a list of rows, with - breadcrumbs, Back and Escape). A moment can stand for one action or, when - a request's or subscription's row was picked (`whole`), every action of - that group up to it (`momentEntries` in `preview/store/actionGroups.ts`), - so an optimistic update and its response show as one effect. Two tabs at - the left end of the bar (`role="tablist"`), **State** and **Action**, - show the subject; the one picked, and State's Snapshot or Diff, are each - Playground's own (state of the panel), while the table or tree view is - shared across them (`useTabStorage`). - - **State** shows the subject at the moment, as one of two icon toggles - at the bar's right end says (`aria-pressed`, beside the table and tree - view switch); both share the subject's stack: - - **Snapshot**: the subject at the moment (table or tree); live, the - store as it is. A moment the store never saw (a fetch, a subscribe) - shows the store as the last action before it left it. - - **Diff**: only what the moment's action (or group) changed at that - level, from before its first action to the store the moment shows - (`diffModel` in `preview/store/diffModel.ts`, with the changes from - `log.spanChanges`, which merges a group's with `mergeChanges` so another - action's rows in between are left out, while a row both changed shows as - it ended up). The store and its lists keep only the rows it changed, a - removed one as it was, each row marked `data-change` through - `DiffContext` and each field it changed `data-changed` (`added` when - the update added it, fresh-colored like an added row), with the - sections it left empty hidden; a record, or a level it left alone, says what it did there with `SubjectChanges` from - `preview/store/ActionDetail.tsx`. Live, it shows the newest stored - action's whole group, so a response that stored nothing new still shows - its request's optimistic update (Live on the scrubber is marked as the - moment). - - **Action**: the moment's action at full width (`{ kind: 'action', seq }`, - `ActionDetail`: what it did to the subject, then the action's fields; - live, `seq: null`, the subject's newest action, garbage collection - aside, as its whole request when it has several actions, so an - optimistic update shows with its response, with "newest" by its crumb). A line above its crumbs, so they head the - action, and one stuck to the bottom (`ActionStep`) name the subject's actions before and after it (as ‹ › - step, `stepMoment`; past the newest is live), and a click makes that the - moment, in the same level. Its stack opens at the action over the - subject's actions in full (`{ kind: 'actions' }`, `ActionsLevel` in - `preview/store/ActionList.tsx`, a `region` with its row count beside the - crumbs "Actions of "), which Back, its crumb and the - scrubber's list button go to, and picking the Action tab again leaves - for the moment's action; while it shows, a mark picked on the - timeline (the timelines' `onMark`) opens its action, as a row does, while ‹ › only move - the moment. Picking a step there sets the moment and - opens the action over the list; picking a row of several actions opens - the group (`whole`: what they did together, then its actions, each - opening its own). Chips drill on in the tab. Stepping the moment moves - that level to the new action, and going live to the newest - (`followMoment`). - - Both stacks stay mounted while their tab is hidden, keeping their levels' - stores, scroll, pages and filters. A record's "changed by" names the kept - action that made the value shown (the latest at or before the moment, live - included; "actions not kept" when the log dropped it) and opens it, moving - the moment. A level a chip opened at an action shows that store, not the - diff, until the moment is set on purpose (`clearAt`), which outranks it. - The list is another way to see more of the timeline, so its button sits - at the scrubber's right end beside the ▾ ("Actions", `aria-pressed` while - the list shows): a click opens - the list in the Action tab, and the mouse resting on it, unless the list - shows, peeks at the same list (`ActionsPane`, an `aside` whose head counts - its rows): an overlay over the panel's right side (narrow, most of it), - dropping from right under the button, - that stays while the pointer is over either and goes as it leaves both, - with Escape or a press outside (each panel's own: a page holds several), - focus going back to the button. Picking a row or step there only moves - the moment, so the tab under it follows; its chips open in State. - Both list (`ActionList`) the actions that touched the subject - (`subjectFilter` in `preview/store/actionGroups.ts`: at the store every - action that reached it; on a record or list those that changed or stored - again a row it covers, and on a record the kept action each gap of - dropped actions was found at, noted once above a run of them), one row per - request or subscription; a row's ▸ lists its actions. The moment's row is marked (`aria-current`), opened and - scrolled to; nothing is marked while live. ↑ ↓ on a row or step move to - the next one, as the moment; a head of several actions stands for the whole - group, as clicking it does. A row renders - again only as its own group changes (`GroupRow` is memoized; - `subjectFilter` keeps its identity while the record's gaps do, and the - chips' `Nav` reads the model through a ref so it keeps its identity - across commits). - The scrubber across the top of the panel (`Scrubber` in - `preview/store/Timeline.tsx`, a `role="group"`) always shows the whole - history on one lane, fit to the panel: ‹ › and ←→ (from anywhere in the - panel without a use of its own for them, see `usesArrows`, or a - widget that took them with `preventDefault`; the panel alone handles them) step through the changes - to the subject (`subjectFilter`'s `hit`: every stored action at the store; below it the marks that left the subject alone - are dimmed, `data-dim`, and skipped; past the newest, and End, go live), a - mark lands on its action, "Live" lets go. Marks closer on the track than a - mark's width and a gap (`MERGE_PX`) draw as one, at the first of them - (`data-count`; dimmed only if all are), so fast polling stays readable. While the moment is set its second line says "After - ·