Repository navigation
Conversation
Kanti
force-pushed
the
feature/component-docs-overview-tiptap
branch
from
October 7, 2026 13:10
73066d6 to
6239fb6
Compare
Kanti
added this pull request to stack #64
October 7, 2026 13:14
Kanti
force-pushed
the
feature/component-docs-overview-tiptap
branch
4 times, most recently
from
October 7, 2026 15:23
c37a739 to
f6de82d
Compare
Kanti
force-pushed
the
feature/component-docs-overview-tiptap
branch
from
October 7, 2026 15:28
f6de82d to
5133fbf
Compare
Kanti
force-pushed
the
feature/component-docs-overview-tiptap
branch
from
October 7, 2026 15:31
5133fbf to
e227720
Compare
Kanti
force-pushed
the
feature/component-docs-overview-tiptap
branch
2 times, most recently
from
October 7, 2026 15:55
ba584b8 to
585ca3b
Compare
Kanti
commented
Oct 7, 2026
Kanti
force-pushed
the
feature/component-docs-overview-tiptap
branch
6 times, most recently
from
October 8, 2026 10:54
74c3428 to
dee70cf
Compare
Kanti
force-pushed
the
feature/component-docs-overview-tiptap
branch
5 times, most recently
from
October 8, 2026 15:57
024aa0c to
fb59d76
Compare
Kanti
force-pushed
the
feature/component-docs-overview-tiptap
branch
from
October 8, 2026 16:13
fb59d76 to
242a51c
Compare
Kanti
force-pushed
the
feature/component-docs-overview-tiptap
branch
4 times, most recently
from
October 8, 2026 17:14
a9a3e3e to
2bfd9b6
Compare
Kanti
marked this pull request as ready for review
October 8, 2026 17:28
Kanti
force-pushed
the
feature/component-docs-overview-tiptap
branch
2 times, most recently
from
October 8, 2026 18:08
4bf7275 to
cdde871
Compare
Open a component overview when selecting a component in Frontend Studio. Present shared component documentation above its fixture variants, with live previews and Controls for the first example. Outside Production, render the documentation through the same persistent editor used in the Variant Inspector's Documentation tab. Component overview and documentation workflow - Resolve overview metadata directly from the registered component, so components without fixture variants can still display and create their documentation. Opening an empty document does not create a file. - Keep variant examples in fixture declaration order. Render the first preview eagerly and subsequent frames lazily, preserving selected site and language. Avoid unnecessary inspector source rendering for an overview. - Reuse the documentation service, permission and Production write policy, editor, Save/Reset actions, source toggle, Ctrl/Cmd+S shortcut, revision checks and unsaved-change guard introduced by the Documentation tab. - Show rendered Markdown in Production without loading editor assets or issuing editable-documentation requests. Display component lookup and documentation errors through the existing module response. - Share document typography, list markers, link and inline-code colors, code-language highlighting and the dedicated Fluid tokenizer with the inspector. Editing starts in the existing document without replacing its preview or changing its layout on focus. - Start long documents collapsed with a fade and an accessible expansion control. Expand on editor focus and detect when a short document grows past the collapse limit. Keep editor actions outside collapsed content. - Place Reset, Save and the source toggle in a sticky row with an opaque theme background at the overview viewport top, without the inspector's tab-header offset. Support narrow screens and hover/focus visibility. Variant previews and Controls - Resize preview frames to their content, expose expansion for the first example and retain preview status messages and language/site context. - Put Live Controls beneath the first preview and update only that frame. Reuse the existing Controls component with optional actions, wrapping its buttons on narrow screens. - Use the requested light/dark conic background for documentation frames and previews. Give frame padding clamp(0.7rem, 1.5vw, 1rem) and make Docs iframe canvases transparent so the grid continues across their boundary. Retain the endpoint background for standalone component previews. Navigation, tree state and compatibility - Clicking a tree folder selects its first descendant component instead of its first variant. Support nested folders and empty components. - Route overview variant-title links through the existing tree selection and TYPO3 content-container navigation. Preserve site and language and persist the variant identifier and tree identifier only after approval. - Restore the previous tree selection when an ordinary tree navigation is cancelled. Cancelling an overview link leaves the search filter, visible nodes, selection and persisted state intact. - When a linked variant is excluded by search, ask the existing guard before resetting TYPO3 Tree's filter. Synchronize the toolbar input, wait for reloading to finish and then select, expand and focus the target. - Account for TYPO3 13 resetFilter() starting an asynchronous reload without returning its promise and for an absent currentFilterRequest property. Reuse navigation approval so one click triggers one confirmation and one iframe navigation, including the subsequent unload guard. - Load and render the backend content-navigation toggle only on TYPO3 14 and newer, matching the inspector's existing compatibility guard. Live reload and unsaved edits - Expose the controller-assigned component-change-stream URI on the overview root so startup reuses the shared EventSource watcher. - Refresh clean documentation after external Markdown changes and reload every preview after fixture changes while retaining unsaved editor data. - Defer conflicting external documentation refreshes until Reset makes the editor clean. Reuse the watcher across inspector/overview navigation rather than opening a separate change stream. Regression coverage and documentation - Add functional coverage for overview metadata, variant ordering, permission/Production behavior, documentation creation and the watcher URI in both views. Exercise the navigation toggle's TYPO3 version guard. - Add JavaScript and real-browser coverage for empty documents, Save/Reset, keyboard saving, source mode, expansion, external changes, conflicts, sticky actions, theme styling and mobile layouts. - Cover actual overview-link navigation using unmodified released TYPO3 13.4.35 and 14.3.7 Tree, TreeToolbar, Lit, Ajax, debounce and storage code. Test filtered targets, delayed reload and cached restoration, dirty-edit cancellation/approval, selection/focus, persistence and a single prompt. Cache pinned upstream test sources under var/.cache/typo3-tree/. - Check preview backgrounds pixel by pixel in both themes at desktop and mobile widths, including frame resizing, scrolling, reload and expansion. - Keep extension regressions in Tests/browser/ and resolve their tools through the shared private root dependencies. Document the overview workflow, supported test placement and real TYPO3 integration fixtures. - Name the new Fluid template Overview.fluid.html and omit editor and overview screenshots from the committed documentation. Preserve the complete reviewed file tree while consolidating the overview changes into one commit on top of the Documentation-tab feature. The pre-consolidation CI passed all nine jobs, covering JavaScript/TypeScript, the three committed bundles' reproducibility, PHP 8.4/8.5 checks and functional tests with MySQL, MariaDB and PostgreSQL. Related: #24
Kanti
force-pushed
the
feature/component-docs-overview-tiptap
branch
from
October 8, 2026 18:12
cdde871 to
414f63f
Compare
Kanti
added a commit
that referenced
this pull request
Oct 8, 2026
Add a persistent Markdown editor to the Variant Inspector's Documentation tab. Render the document through the editor from the start so entering editing preserves the document's DOM, typography and position without a preview-to-editor replacement. Store documentation beside its registered Fluid component template and share the same Markdown file across variants. Documentation workflow and presentation - Label the inspector tab Documentation and make it the primary editing workflow in the frontend developer README. Explain what to document: component purpose, arguments, variants and practical usage examples. - Share Markdown typography between the editor and rendered documentation, including heading spacing, blue links, Controls-style inline-code colors, visible list markers and light/dark theme styling. - Put Reset, Save and the Markdown/rich-text toggle in one stable action row that appears on hover or focus. Give the source textarea content sizing so it grows and shrinks with the document. - Show an icon toolbar above the caret or selection, with space around the cursor, viewport-aware positioning and 50% opacity until hovered or keyboard-focused. Keep the action row accessible in narrow panels. - Provide PhpStorm-style text names: Normal for paragraphs, Title for H1, Subtitle for H2 and Heading 1-4 for H3-H6. Include previews, H-level hints, groups and checked active choices in the style dropdown. - Group bullets and numbering in a Lists dropdown. Preserve selections through menu focus, support keyboard navigation and Escape, and restore editor focus immediately after applying a choice. - Put Strike after Italic and Code block after Code. Keep Link, Image, Undo and Redo in that order on the second row. Use a prominent active formatting state and keep the two code controls together when wrapping. - Keep insertion actions in the caret toolbar. Omit a table-insertion button while preserving existing tables through unrelated rich edits. Markdown fidelity and code editing - Preserve the original Markdown exactly until a content edit. Compare rendered round trips before enabling rich-text editing and fall back to the original source with a warning when content cannot be preserved. Block rich-text switching while the document remains unsupported. - Support images, quotations, inline code, horizontal rules, lists, headings and existing tables alongside paragraphs and emphasis. - Convert four backticks directly into a code block. Support multiple lines, blank lines, Tab indentation, per-block language selection, independently undoable language changes and Ctrl/Cmd+Enter to exit. - Preserve imported language aliases and unknown language labels. Leave unspecified and unknown languages as plain text. - Share highlighting between editable and rendered code. Add a dedicated Fluid scanner using the PHP inspector's token classes and theme colors for ViewHelper tags/calls, attributes, variables, chains, nested arrays, quoted strings, comments and incomplete expressions. - Keep the Fluid source verbatim and avoid recursive stack growth for deeply nested or unfinished JavaScript input. Make the PHP expression regex's text branch possessive to avoid excessive backtracking. - Add 32 shared PHP/JavaScript token fixtures and browser comparisons against the PHP stylesheet in both themes. Keep HTML/XML separate from Fluid and retain existing language grammars. Persistence, permissions and reload behavior - Add GET/POST documentation handling through TYPO3's backend AJAX route. Require both an authenticated backend user and access to the admin_frontendstudio module for reads and writes. Allow authorized non-admin users and deny other logged-in users with HTTP 403. - Apply the existing Production write policy to documentation. Resolve paths only through registered component templates, support both .html and .fluid.html names, and reject symlinks or non-regular Markdown paths. - Validate UTF-8 content and the 1 MiB size limit. Check the submitted revision under a lock, preserve file permissions and replace content atomically through a temporary sibling file. Return HTTP 409 for a revision conflict and remove the Markdown file when saving empty text. - Submit saves as form fields TYPO3 parses. Preserve edits made during pending saves or reloads, retain conflicting edits and coordinate Ctrl/Cmd+S with the existing Controls keyboard shortcut. - Restore the exact baseline and dirty state on Reset even when editor initialization fails. Synchronize a mounted editor when available and restore rendered content otherwise. Retain pending-request protection. - Guard navigation and iframe unload against unsaved documentation. Extend the existing file watcher and EventSource messages to include Markdown changes. Refresh clean documents and preserve pending edits. - Rename Fluid templates and functional fixtures to .fluid.html and adjust snapshot fixture paths and normalized route-token expectations for the additional Documentation tab. JavaScript dependencies, builds and CI - Use one private root package.json and package-lock.json for contributor build and test dependencies, with exact dependency versions. Keep Playwright as the only workspace and preserve its consumer dependencies, TypeScript exports, source files and TypeScript configuration. - Keep existing .test.ts files in Playwright/src. Move the two standalone Playwright/browser checks to Tests/browser and put new extension tests there. Remove obsolete browser-file arguments from the package-local test script. Keep consumer helpers supplied directly as TypeScript. - Run both test locations from the root scripts and check TypeScript without emitting JavaScript. Reuse Playwright's strict compiler options while skipping incompatible third-party DOM declaration checks. - Build the editor, code highlighter and Markdown converter with the same npm/esbuild tooling. Commit all three bundles under Resources/Public/ Contrib and embed required third-party notices. Preserve public exports and keep Node.js, npm and CDN dependencies out of TYPO3 runtime use. - Follow TYPO3 test-runner conventions with pinned Node.js 24.19.0 in Docker/Podman, a cached Chromium image, fail-fast npm ci, direct npm argument forwarding and the unitJavascript alias. - Add javascript, javascriptBuild, javascriptBuildCheck and npm suites to runTests.sh. Keep PHP suites independent of JavaScript installation and rebuilding, and document the suites in help output. - Make the build check install locked dependencies and regenerate all expected bundles in memory. Reject missing, untracked, modified or outdated output by comparing generated and working content with HEAD. - Run JavaScript/TypeScript and bundle reproducibility as separate required pull-request CI jobs using the same runner commands as local development. - Document test placement, package responsibilities and contributor commands in the dedicated READMEs and AGENTS.md. Keep the root README's JavaScript explanation to two short linked sentences plus check commands. Present runner commands first and local npm commands as secondary options. - Set browser-test selection and focus through the editor model before typing so Markdown preservation and Fluid highlighting checks avoid asynchronous DOM-caret synchronization. Validation - All 211 JavaScript/browser tests and the no-emit TypeScript check passed in the pinned Node.js 24.19.0/Chromium environment. - The package-local npm test --prefix Playwright command passed all 119 existing tests. Fluid typing/highlighting passed six additional light/dark repetitions with a single CPU. - All three committed bundles passed javascriptBuildCheck. Bundle builds and deliberate modification rejection were verified, including the required third-party license notices. - All 169 TYPO3 functional tests passed with MySQL on PHP 8.5. Relevant permission, Production, revision-conflict, watcher and inspector cases are included in that suite. - GrumPHP, PHPStan, Rector, style checks, JSON validation and Composer audit passed. Documentation links and shell help/syntax were checked. - The complete #62 CI run passed all nine jobs: JavaScript/TypeScript, bundle reproducibility, PHP 8.4/8.5 unit and quality checks, and functional tests with MySQL, MariaDB and PostgreSQL. Implement #10 as the Documentation-tab foundation for stacked PR #63. The separate Documentation overview remains in #63; this commit contains the complete #62 changes relative to main.
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
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.
Selecting a component opens its Docs overview with shared documentation and variant previews. Outside Production, the documentation uses the same persistent editor as the variant inspector's Documentation tab, with Save, Reset, source mode, the text-style dropdown and highlighted code blocks. It inherits #62's two-row formatting toolbar with PhpStorm-style heading names, checked style previews and a grouped Lists menu, Reset fallback after editor initialization failure, one private root package for build tooling and tests in
Playwright/src/andTests/browser/, TYPO3-style Node/browser runner conventions, and automatic bundle reproducibility checks. Production displays rendered documentation without loading the editor.This is the alternative to #49, stacked on #62 (the alternative to #44). The original #44 → #49 stack remains available for comparison.
resetFilter()API and synchronize the toolbar input after navigation approval. The navigation waits for TYPO3 13's asynchronous reload even though its reset API returns no promise. Cancelling an Overview link leaves the filter, visible nodes, selection and saved state untouched; ordinary tree-click cancellation still restores the previous selection. State is persisted only after approval. Discard approval covers the ensuing iframe unload so one click produces one navigation and one confirmation.clamp(0.7rem, 1.5vw, 1rem). Transparent Docs iframe canvases show one continuous grid across the frame and its padding. Live Controls beneath the first preview affect only that preview; variant titles open their inspectors.Related: #24. Merge #62 before retargeting this PR to
main.Tests/browser/, and the overview template isOverview.fluid.html. Contributor documentation andAGENTS.mdinherit [FEATURE] Add a documentation editor to the Documentation tab #62's explicit test-placement and public-package rules.