Integrate Navigation & OData V4 tutorials; align all packages and rework TS/JS download links#302
Closed
petermuessig wants to merge 10 commits into
Closed
Integrate Navigation & OData V4 tutorials; align all packages and rework TS/JS download links#302petermuessig wants to merge 10 commits into
petermuessig wants to merge 10 commits into
Conversation
Bring two new tutorials — Navigation and Routing, OData V4 — into the monorepo, and rework all four tutorials onto a single template so they share the same toolchain, layout, namespace, and documentation conventions. Tutorials - packages/navigation/ — 17 steps imported from the OpenUI5 demokit, promoted to the standard `steps/` layout, package names changed to `ui5.tutorial.navigation.stepNN`, ui5.yaml metadata aligned with the rest of the repo, dev dependencies switched to the walkthrough set (@types/openui5, ui5-middleware-serveframework, ui5-tooling-transpile), app namespace renamed `sap.ui.demo.nav` -> `ui5.tutorial.navigation` across manifests, TS imports, JSDoc, XML controllerName, tsconfig paths, and HTML resource-roots. - packages/odatav4/ — 11 steps imported from the same demokit source, restructured from `solutions/` -> `steps/`, root-level markdown moved into per-step README.md, shared `images/` split into per-step `assets/`. JS sources fully converted to TypeScript ES modules (Component, App.controller, model/models, initMockServer, the ~800- line sinon-based mock server, view XML), Hungarian variable prefixes stripped (oModel -> model, aMatches -> matches, sUrl -> url, ...) to match the project's TS style. App namespace standardised to `ui5.tutorial.odatav4`. Namespace alignment across the existing tutorials - packages/walkthrough/ renamed `ui5.walkthrough` -> `ui5.tutorial.walkthrough` across ~630 files (manifests, TS imports + @namespace, XML controllerName + xmlns, tsconfig paths, HTML resource-roots, every README code snippet, step package.json names). - packages/quickstart/ renamed `ui5.quickstart` -> `ui5.tutorial.quickstart` with the same shape across 27 files; ui5.yaml `metadata.name` `quickstart-tutorial` -> `ui5.tutorial.quickstart`. After this commit, all 69 step workspaces follow the same naming convention: `ui5.tutorial.<tutorial>.stepNN`. Documentation - Per-tutorial overview READMEs (packages/{navigation,odatav4}/README.md) now mirror packages/walkthrough/README.md: each step bullet has an inline `[🔗 Live Preview]` link and paired `<details class="ts-only">` / `<details class="js-only">` `[📥 Download Solution]` blocks. - Step READMEs ship with paired ```ts / ```js code blocks so the Jekyll code-couple toggle renders both flavours. JS half generated from the build's sanitized `*-dbg.js` output where applicable. - Folder-structure images replaced with fenced ```text ASCII trees (using `.?s` placeholders so the global toggle flips the extensions); images deleted from the per-step assets. - All callout syntaxes (GitHub-flavoured alerts `> [!NOTE]` plus walkthrough's emoji blockquotes `> 📝 **Note:** <br>`) normalised to the `:note:` / `:tip:` / `:info:` / `:caution:` / `:warning:` shorthand mandated by `_/AUTOMATE.md`. - Step-level "view and download all files at \[demokit\]" links retargeted to the published `https://ui5.github.io/tutorials/...` URLs so they resolve against the local dist via the dev server. - License year bumped 2025 -> 2026 across all overview READMEs; `## License` sections added to the navigation and odatav4 overviews to match the walkthrough/quickstart convention. Tooling - tools/dev-server/server.js: mount `dist/` under `/dist/...` so `npm start` serves the locally-built apps and ZIPs; rewrite the published `https://ui5.github.io/tutorials/...` URLs in rendered markdown to the local `/dist/...` paths for the four known tutorial slugs (walkthrough, quickstart, navigation, odatav4); friendly hint page when an artifact is missing. - README.md: document the `npm install && npm run build && npm start` workflow. Verification - `npm install` succeeds and registers all 69 workspaces under the new `ui5.tutorial.*` namespace. - `npm run typecheck -ws --if-present` exits 0. - `npm run build` exits 0; produces `dist/<tutorial>/build/NN/` apps, `<tutorial>-step-NN.zip` and `<tutorial>-step-NN-js.zip` downloads, and the rewritten `dist/index.md` overview for each tutorial. - `index-cdn.html` present for every webapp that bootstraps SAPUI5 (68 of 69 — walkthrough step 01 is the bare HTML "Hello World" and intentionally has none). - Dev-server smoke test: Live Preview links from the overview README resolve to `/dist/<tutorial>/build/NN/index-cdn.html` with HTTP 200.
Versions - Bump framework to OpenUI5 1.148.1 (latest LTS patch) in every step ui5.yaml and CDN bootstrap URL. - Bump manifest _version to 2.8.0 and minUI5Version to 1.148 across all 69 manifests (mapping per UI5/manifest v2/mapping.json). - specVersion: "4.0" for every ui5.yaml. - @types/openui5 ^1.148.0 in every step package.json. - Sync README narrative and inline manifest snippets that referenced OpenUI5 1.120 / _version 1.60.0 / 1.38.0 to the new values. Reviewer findings (PR #295, @flovogt) - Manifest v2 (_version 2.8.0). - specVersion '4.0'. - Ensure trailing newline on every webapp source file. Cross-tutorial inconsistency cleanup - Quickstart Component.ts: @namespace sap.m.tutorial.quickstart.NN -> ui5.tutorial.quickstart, switch to public static metadata and add interfaces: ["sap.ui.core.IAsyncContentCreation"]. - Strip residual Hungarian-notation in quickstart controllers/index.ts (oEvent/bState/oView) and the named identifiers in odatav4 OPA tests (iGrowingBy/sViewName/oListBinding). - Add explicit "strict": false, "strictNullChecks": false to walkthrough and quickstart tsconfig.json files (match navigation/odatav4). - Drop redundant data-sap-ui-libs from quickstart steps 02 and 03 index.html (Component manifest already declares the libs). - Add data-sap-ui-theme="sap_horizon" to quickstart and navigation bootstrap script tags so the theme is explicit and consistent with walkthrough/odatav4. Indentation normalization per .editorconfig - JSON / XML / YAML / .properties -> 2 spaces. - TS / JS / HTML -> tabs. - Re-indent fenced code blocks inside step README.md files to match the same conventions so doc snippets mirror the actual source files. Verified: npm run typecheck and npm run build both exit 0; ui5-linter clean on sampled steps; manifest validation clean.
Replace deprecated @types/openui5 package with the official @openui5/types package across all tutorial packages and steps. Updates include: - package.json: @types/openui5 → @openui5/types in devDependencies - tsconfig.json: Updated types array entries - README.md: Updated documentation references This aligns with the OpenUI5 project's official type definitions package.
- tsconfig.json: drop unused "node" type from the `types` array across all 67 step packages. The webapp sources are browser code and don't use any Node.js globals. - tsconfig.json: add explicit "@types/qunit" to the `types` array in the 14 packages that contain QUnit test files (walkthrough steps 27-38, odatav4 steps 08 and 11). - package.json: add "@types/qunit": "2.5.4" as a devDependency to those same 14 packages so the type package resolves via the standard node_modules/@types lookup rather than depending on transitive install layout. - package.json: bump "@openui5/types" from ^1.148.0 to ^1.148.1 across all 67 step packages, aligning with the 1.148.1 references already present in ui5.yaml and the index-cdn.html bootstrap URLs. Verified with `npm run typecheck` across all workspaces.
…tion-odatav4-tutorials # Conflicts: # package-lock.json
The init() callback destructured the sinon module into a parameter named `sinon`, then executed `sinon = sinon` — a no-op that shadowed the module-scoped `sinon` binding and left it `undefined` outside the callback. Rename the parameter to `lazySinon` and assign it through so subsequent code (e.g. `sinon.fakeServer`) sees the loaded module.
Steps 08 and 11 shipped OPA5 tests using the legacy demokit namespace `sap.ui.core.tutorial.odatav4`, while the app's manifest declares `sap.app.id` as `ui5.tutorial.odatav4`. As a result `iStartMyUIComponent` could not resolve the component and no journey ran. Rename the namespace to `ui5.tutorial.odatav4` (dot form) and `ui5/tutorial/odatav4` (slash form) in every affected test module — `opaTests.qunit.html` resource-roots, module require paths, the `Opa5.extend` class name, `componentConfig.name`, and `viewNamespace`.
…step 01 Address review feedback from @akudev: * JSDoc `@param` names in every mockserver still used Hungarian prefixes (`sUrl`, `sUserName`, `sBody`, `sKey`), while the actual TypeScript parameters were already renamed to `url`, `userName`, `body`, `key`. Rename the JSDoc params to match — applied uniformly across all 11 `packages/odatav4/steps/*/webapp/localService/mockserver.ts` files. * Finish the `sinon = sinon` self-assignment fix in step 01 that was overlooked in ea3ff65 — parameter shadowing left the module-scoped `sinon` binding `undefined` outside the require callback. Rename the callback param to `lazySinon` and assign it through, matching the pattern already in steps 02-11.
Address review feedback from @akudev — three README-vs-code drifts: * `"_version": "1.12.0"` in `manifest.json` snippets across navigation steps 02, 06, 07, 08, 09, 10, 11, 12 and odatav4 step 03 disagreed with the shipped `manifest.json` files, which use `"2.8.0"`. Update the READMEs to match. * `packages/quickstart/steps/01/README.md` still documented `"types": ["node", "@openui5/types"]` even though the tsconfig no longer declares Node.js types. Drop `"node"` from the JSON snippet and rewrite the explanation to describe the single-entry `types` array. * `packages/odatav4/steps/01/README.md` linked back to step 11 as `Previous`, which does not make sense for the first step. Remove the stale `Previous` line.
Two related passes over the tutorial corpus:
1. Content normalization (all four tutorials): migrate the retired `.?s`
filename placeholder to `.ts/.js`, add descriptive image alt text in
place of bare ``, add first-line path comments to ts/js code
fences, and align README snippets with the shipped configuration.
2. TS/JS download links: replace the paired
`<details class="ts-only|js-only" markdown="1">…</details>` wrappers
around download-solution links with inline
`<span class="ts-only|js-only">…<span class="lang-suffix"> (TS|JS)</span></span>`.
Both language variants now read plainly in raw markdown (distinct
`(TS)` / `(JS)` labels) while the rendered site still shows only the
active language — the existing `.ts-only`/`.js-only` CSS hides the
inactive span and a new `.lang-suffix { display: none }` rule drops
the marker. No runtime JS change needed. Covers the per-step block
form, the overview inline form, and the two standalone-bundle links
in navigation/odatav4 step 01.
Also add AGENTS.md (repo guide for AI agents) documenting layout,
conventions, propagation rules, and how to use the tutorials as a
codegen source; document the new `<span>` link pattern in AGENTS.md
and CONTRIBUTING.md; and regenerate packages/*/steps.json.
The one-off migration script lives under the gitignored `_/` folder.
Contributor
Author
|
Superseded by #303. Since #295 landed on |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This branch brings the Navigation and Routing and OData V4 tutorials into the monorepo and aligns all four tutorials (quickstart, walkthrough, navigation, odatav4) to a consistent shape on OpenUI5 1.148 LTS.
The most recent commit reworks how the JS/TS download links are structured across every step, based on the observation that the old
<details>wrappers rendered as noisy collapsibles in the raw-markdown view (and to AI tools indexing the corpus).What's in the branch
@types/openui5→@openui5/types, tsconfig cleanup, namespace/OPA5 fixes..?sfilename placeholder in favor of.ts/.js, add descriptive image alt text, add first-line path comments to ts/js code fences, align README snippets with shipped config.<details class="ts-only|js-only" markdown="1">…</details>wrappers with inline<span class="ts-only|js-only">…<span class="lang-suffix"> (TS|JS)</span></span>. Both language variants now read plainly in raw markdown with distinct(TS)/(JS)labels, while the rendered site still shows only the active language. Achieved with no runtime JS change — the existing.ts-only/.js-onlyCSS hides the inactive span, and a new.lang-suffix { display: none }rule drops the marker.AGENTS.md— a repo guide for AI agents: layout, toolchain, authoring conventions, propagation rules, and how to use the tutorials as a codegen source (anchor on the last step, not the first). The new<span>link pattern is documented here and inCONTRIBUTING.md.How the download-link change works
📥 Download Solutionlabels… (TS)and… (JS)Verification
packages/*/steps.jsonregenerated byte-identically — the generator's class-based regex still matches the new<span>shape.<details class="ts-only">blocks used for language-only prose are intentionally left untouched.-js.zipbundles confirmed to exist for the standalone-bundle links.🤖 Generated with Claude Code