Skip to content

[FEATURE] Add an editable component documentation view - #63

Merged
Kanti merged 1 commit into
feature/component-doc-tab-tiptapfrom
feature/component-docs-overview-tiptap
Oct 8, 2026
Merged

Kanti merged 1 commit into
feature/component-doc-tab-tiptapfrom
feature/component-docs-overview-tiptap

Conversation

@Kanti

@Kanti Kanti commented Oct 7, 2026 •

Copy link
Copy Markdown
Member

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/ and Tests/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.

  • Clicking a component-tree folder selects its first descendant component and opens that component's Docs overview, including nested folders and components without fixture variants.
  • Empty documentation can be created directly in the overview, including components without fixture variants. Opening the view does not create a file.
  • Save/Reset, toolbar Ctrl/Cmd+S, revision conflicts and unsaved-change protection use the existing documentation workflow. The Overview exposes the assigned live-reload URI to the existing shared EventSource watcher. External documentation changes refresh clean documents; fixture changes refresh every preview while unsaved documentation stays intact. Pending documentation changes are fetched after Reset makes the editor clean.
  • Long documentation starts collapsed with a fade and expands on focus for editing, including when a short document grows beyond the collapse limit. Its actions remain outside the collapsed content.
  • The overview imports and renders the content-navigation toggle only on TYPO3 14+, matching the inspector's version guard.
  • Overview variant-title links select their variant through the existing tree navigation and TYPO3 content container, preserving site and language. Filtered-out variants clear the active search through TYPO3 Tree's existing 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.
  • The sticky Reset/Save/source-toggle row uses the overview's opaque theme background and sticks at the viewport top, without the inspector tab-header offset.
  • The overview and inspector share typography, link and inline-code colors, list markers and language highlighting. Fluid code blocks inherit [FEATURE] Add a documentation editor to the Documentation tab #62's dedicated tokenizer and match the PHP inspector's tokens and theme colors; HTML/XML remains a separate language.
  • Variant previews retain fixture declaration order, lazy loading, resizing and site/language context. The preview view and Docs frames use the requested light/dark conic background, with Docs frame padding 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.

@Kanti
Kanti force-pushed the feature/component-docs-overview-tiptap branch from 73066d6 to 6239fb6 Compare October 7, 2026 13:10
@Kanti
Kanti added this pull request to stack #64 October 7, 2026 13:14
@Kanti
Kanti force-pushed the feature/component-docs-overview-tiptap branch 4 times, most recently from c37a739 to f6de82d Compare October 7, 2026 15:23
@Kanti Kanti changed the title [FEATURE] Add component Docs overviews on the Tiptap editor stack [FEATURE] Add editable component Docs overviews on the Tiptap stack Oct 7, 2026
@Kanti
Kanti force-pushed the feature/component-docs-overview-tiptap branch from f6de82d to 5133fbf Compare October 7, 2026 15:28
@Kanti
Kanti force-pushed the feature/component-docs-overview-tiptap branch from 5133fbf to e227720 Compare October 7, 2026 15:31
@Kanti
Kanti force-pushed the feature/component-docs-overview-tiptap branch 2 times, most recently from ba584b8 to 585ca3b Compare October 7, 2026 15:55
Comment thread Documentation/docs-overview-editor.png Outdated
@Kanti
Kanti force-pushed the feature/component-docs-overview-tiptap branch 6 times, most recently from 74c3428 to dee70cf Compare October 8, 2026 10:54
@Kanti Kanti changed the title [FEATURE] Add editable component Docs overviews on the Tiptap stack [FEATURE] Add an editable component documentation view Oct 8, 2026
@Kanti
Kanti force-pushed the feature/component-docs-overview-tiptap branch 5 times, most recently from 024aa0c to fb59d76 Compare October 8, 2026 15:57
@Kanti
Kanti force-pushed the feature/component-docs-overview-tiptap branch from fb59d76 to 242a51c Compare October 8, 2026 16:13
@Kanti
Kanti force-pushed the feature/component-docs-overview-tiptap branch 4 times, most recently from a9a3e3e to 2bfd9b6 Compare October 8, 2026 17:14
@Kanti
Kanti marked this pull request as ready for review October 8, 2026 17:28
@Kanti
Kanti force-pushed the feature/component-docs-overview-tiptap branch 2 times, most recently from 4bf7275 to cdde871 Compare October 8, 2026 18:08
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
Kanti force-pushed the feature/component-docs-overview-tiptap branch from cdde871 to 414f63f Compare October 8, 2026 18:12
@Kanti
Kanti merged commit d56666d into main Oct 8, 2026
9 checks passed
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.
@Kanti
Kanti deleted the feature/component-docs-overview-tiptap branch October 8, 2026 18:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant