@ckeditor/ckeditor5-dev-manual-server 57.0.0-alpha.0 → 57.0.0

package/theme/manual-header.ts

@@ -0,0 +1,193 @@
+/**
+ * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+// Shadow DOM chrome styles and document-scoped instruction typography.
+// Imported as raw strings so they can be adopted into constructable stylesheets.
+import headerStyles from './manual-header.css?inline';
+import instructionsStyles from './manual-instructions.css?inline';
+
+const MANUAL_HEADER_DATA_META = 'ck-manual-header';
+
+const headerStyleSheet = createStyleSheet( headerStyles );
+const instructionsStyleSheet = createStyleSheet( instructionsStyles );
+
+/* eslint-disable @stylistic/max-len */
+const TEMPLATE = /* html */ `
+	<div class="bar">
+		<a class="pill back" title="Back to test index">&larr; All tests</a>
+		<span class="divider" aria-hidden="true"></span>
+		<span class="label">
+			<span class="label__name" data-field="name"></span>
+			<span class="label__package" data-field="package"></span>
+		</span>
+		<span class="divider instructions-only" aria-hidden="true"></span>
+		<button type="button" class="pill instructions-only" data-action="toggle" aria-expanded="false">
+			Instructions
+		</button>
+	</div>
+	<aside class="panel" aria-hidden="true" inert>
+		<div class="panel__inner">
+			<header class="panel__header">
+				<div class="panel__titles">
+					<h1 class="panel__title" data-field="name"></h1>
+					<code class="panel__package" data-field="package"></code>
+				</div>
+				<button type="button" class="panel__close" data-action="close" aria-label="Close">
+					<svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true">
+						<path fill="currentColor" d="M3.72 3.72a.75.75 0 011.06 0L8 6.94l3.22-3.22a.75.75 0 111.06 1.06L9.06 8l3.22 3.22a.75.75 0 11-1.06 1.06L8 9.06l-3.22 3.22a.75.75 0 01-1.06-1.06L6.94 8 3.72 4.78a.75.75 0 010-1.06z"/>
+					</svg>
+				</button>
+			</header>
+			<article class="panel__body"><slot></slot></article>
+		</div>
+	</aside>
+`;
+/* eslint-enable @stylistic/max-len */
+
+/**
+ * `<ck-manual-header>` renders the manual test chrome: a fixed header bar with the test
+ * name, package name and a back-to-index link, plus a collapsible instructions panel that
+ * projects the element's light-DOM children (default slot).
+ *
+ * The manual test server injects a `<meta name="ck-manual-header">` carrying the package
+ * name and the base-aware catalog href, and the `<script>` that defines this
+ * element — only on pages whose source contains `<ck-manual-header`. Pages without the
+ * element render with no chrome. The invisible environment setup (license key, inspector,
+ * refresh prompt) lives in `manual-bootstrap.ts` and is injected into every manual test page.
+ *
+ * Without this script the element is unknown and its children render as plain readable markup.
+ */
+class ManualHeaderElement extends HTMLElement {
+	private _panel!: HTMLElement;
+
+	constructor() {
+		super();
+
+		const shadow = this.attachShadow( { mode: 'open' } );
+
+		shadow.adoptedStyleSheets = [ headerStyleSheet ];
+		shadow.innerHTML = TEMPLATE;
+	}
+
+	public connectedCallback(): void {
+		adoptInstructionsStyles();
+
+		const data = readManualHeaderData();
+		const shadow = this.shadowRoot!;
+
+		this._panel = shadow.querySelector<HTMLElement>( '.panel' )!;
+
+		const backLink = shadow.querySelector<HTMLAnchorElement>( '.back' )!;
+
+		backLink.href = data.catalogHref;
+
+		for ( const element of shadow.querySelectorAll<HTMLElement>( '[data-field="name"]' ) ) {
+			element.textContent = this._resolveDisplayName();
+		}
+
+		for ( const element of shadow.querySelectorAll<HTMLElement>( '[data-field="package"]' ) ) {
+			element.textContent = data.packageName;
+		}
+
+		this._setUpInstructions();
+		this._setUpActions( shadow );
+	}
+
+	/**
+	 * The visible name comes from the first slotted heading if present, otherwise `document.title`,
+	 * falling back to the test path relative to `tests/manual/` derived from the page URL.
+	 * This avoids `<title>`/instructions drift while letting authors override it with a heading.
+	 */
+	private _resolveDisplayName(): string {
+		const heading = this.querySelector( 'h1, h2, h3, h4, h5, h6' );
+		const headingText = heading?.textContent?.trim();
+
+		return headingText || document.title.trim() || getSlugFromLocation();
+	}
+
+	/**
+	 * Toggles the availability of the instructions panel based on whether the default slot has
+	 * meaningful content.
+	 */
+	private _setUpInstructions(): void {
+		const slot = this.shadowRoot!.querySelector<HTMLSlotElement>( 'slot' )!;
+		const update = (): void => {
+			this.toggleAttribute( 'has-instructions', hasSlottedContent( slot ) );
+		};
+
+		update();
+		slot.addEventListener( 'slotchange', update );
+	}
+
+	private _setUpActions( shadow: ShadowRoot ): void {
+		shadow.addEventListener( 'click', event => {
+			const trigger = ( event.target as Element ).closest<HTMLElement>( '[data-action]' );
+
+			if ( !trigger ) {
+				return;
+			}
+
+			if ( trigger.dataset.action == 'toggle' ) {
+				this._toggleInstructions( !this._panel.classList.contains( 'panel--open' ) );
+			} else if ( trigger.dataset.action == 'close' ) {
+				this._toggleInstructions( false );
+			}
+		} );
+
+		document.addEventListener( 'keydown', event => {
+			if ( event.key == 'Escape' ) {
+				this._toggleInstructions( false );
+			}
+		} );
+	}
+
+	private _toggleInstructions( isOpen: boolean ): void {
+		const trigger = this.shadowRoot!.querySelector<HTMLElement>( '[data-action="toggle"]' )!;
+
+		this._panel.classList.toggle( 'panel--open', isOpen );
+		this._panel.toggleAttribute( 'inert', !isOpen );
+		this._panel.setAttribute( 'aria-hidden', String( !isOpen ) );
+		trigger.setAttribute( 'aria-expanded', String( isOpen ) );
+	}
+}
+
+function readManualHeaderData(): { packageName: string; catalogHref: string } {
+	const meta = document.querySelector<HTMLMetaElement>( `meta[name="${ MANUAL_HEADER_DATA_META }"]` );
+
+	return {
+		packageName: meta?.dataset.packageName || '',
+		catalogHref: meta?.dataset.catalogHref || '/'
+	};
+}
+
+function getSlugFromLocation(): string {
+	const path = decodeURIComponent( window.location.pathname );
+	const slugPath = path.split( '/tests/manual/' )[ 1 ] || path.split( '/' ).pop() || '';
+
+	return slugPath.replace( /\.manual\.html$/, '' );
+}
+
+function hasSlottedContent( slot: HTMLSlotElement ): boolean {
+	return slot.assignedNodes().some( node =>
+		node.nodeType == Node.ELEMENT_NODE ||
+		node.nodeType == Node.TEXT_NODE && Boolean( node.textContent?.trim() )
+	);
+}
+
+function createStyleSheet( css: string ): CSSStyleSheet {
+	const sheet = new CSSStyleSheet();
+
+	sheet.replaceSync( css );
+
+	return sheet;
+}
+
+function adoptInstructionsStyles(): void {
+	if ( !document.adoptedStyleSheets.includes( instructionsStyleSheet ) ) {
+		document.adoptedStyleSheets = [ ...document.adoptedStyleSheets, instructionsStyleSheet ];
+	}
+}
+
+customElements.define( 'ck-manual-header', ManualHeaderElement );

package/theme/manual-instructions.css

@@ -0,0 +1,130 @@
+/**
+ * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/*
+ * Adopted into the *document* (not the shadow root) by the <ck-manual-header> component.
+ *
+ * The instructions are authored as light-DOM children of <ck-manual-header> and projected
+ * into the shadow slot. Because slotted content stays in the light DOM, `::slotted()` cannot
+ * reach nested nodes, so instruction typography is scoped here to `ck-manual-header` descendants.
+ */
+
+/* Offset for the fixed header bar injected by the component. */
+body {
+	padding-top: var( --ck-manual-header-height, 44px );
+}
+
+ck-manual-header {
+	font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+	line-height: 1.6;
+	color: #0a0a0a;
+}
+
+ck-manual-header h1,
+ck-manual-header h2,
+ck-manual-header h3,
+ck-manual-header h4,
+ck-manual-header h5,
+ck-manual-header h6 {
+	margin: 24px 0 8px;
+	font-weight: 600;
+	letter-spacing: -0.01em;
+	line-height: 1.3;
+}
+
+ck-manual-header h1 { font-size: 20px; }
+ck-manual-header h2 { font-size: 17px; }
+ck-manual-header h3 { font-size: 15px; }
+ck-manual-header h4,
+ck-manual-header h5,
+ck-manual-header h6 { font-size: 14px; }
+
+ck-manual-header > :first-child { margin-top: 0; }
+ck-manual-header > :last-child { margin-bottom: 0; }
+
+ck-manual-header p {
+	margin: 8px 0;
+}
+
+ck-manual-header ul,
+ck-manual-header ol {
+	margin: 8px 0;
+	padding-left: 24px;
+}
+
+ck-manual-header li {
+	margin: 3px 0;
+}
+
+ck-manual-header code {
+	padding: 1px 6px;
+	border-radius: 4px;
+	background: #f0f0f0;
+	font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+	font-size: 0.9em;
+}
+
+ck-manual-header kbd {
+	padding: 1px 6px;
+	border: 1px solid rgb(0 0 0 / 15%);
+	border-bottom-width: 2px;
+	border-radius: 4px;
+	background: #fafafa;
+	font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+	font-size: 0.85em;
+}
+
+ck-manual-header pre {
+	margin: 12px 0;
+	padding: 12px 14px;
+	border-radius: 8px;
+	background: #f5f5f5;
+	overflow-x: auto;
+	font-size: 12px;
+	line-height: 1.5;
+}
+
+ck-manual-header pre code {
+	padding: 0;
+	background: transparent;
+	font-size: inherit;
+}
+
+ck-manual-header a {
+	color: #1d4ed8;
+	text-decoration: underline;
+	text-underline-offset: 2px;
+}
+
+ck-manual-header blockquote {
+	margin: 12px 0;
+	padding: 4px 14px;
+	border-left: 3px solid rgb(0 0 0 / 15%);
+	color: #525252;
+}
+
+ck-manual-header table {
+	margin: 12px 0;
+	border-collapse: collapse;
+	font-size: 13px;
+}
+
+ck-manual-header th,
+ck-manual-header td {
+	padding: 6px 10px;
+	border: 1px solid rgb(0 0 0 / 10%);
+	text-align: left;
+}
+
+ck-manual-header th {
+	background: #f5f5f5;
+	font-weight: 600;
+}
+
+ck-manual-header hr {
+	margin: 16px 0;
+	border: 0;
+	border-top: 1px solid rgb(0 0 0 / 10%);
+}

package/dist/manual-test-plugin/parse-markdown.d.ts

@@ -1,6 +0,0 @@
-/**
-* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
-* For licensing, see LICENSE.md.
-*/
-import type { ManualPageEntry } from "./types.js";
-export declare function loadRenderedInstructions(entry: ManualPageEntry, workspaceRoot: string): string;

package/dist/manual-test-plugin/shell-html.d.ts

@@ -1,14 +0,0 @@
-/**
-* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
-* For licensing, see LICENSE.md.
-*/
-import type { ManualPageEntry } from "./types.js";
-export interface CreateManualShellHtmlOptions {
-	catalogPublicPath?: string;
-	entry: ManualPageEntry;
-	html: string;
-	shellScriptPublicPath: string;
-	shellTemplateFilePath: string;
-	workspaceRoot: string;
-}
-export declare function createManualShellHtml({ catalogPublicPath, entry, html, shellScriptPublicPath, shellTemplateFilePath, workspaceRoot }: CreateManualShellHtmlOptions): string;

package/theme/shell.css

@@ -1,361 +0,0 @@
-.manual-test-container {
-	min-width: 0;
-	box-sizing: border-box;
-	padding: calc( var( --shell-height, 44px ) + 8px ) 8px 8px;
-}
-
-body.shell-enabled {
-	box-sizing: border-box;
-}
-
-.shell {
-	position: fixed;
-	top: 0;
-	left: 0;
-	right: 0;
-	z-index: 99999;
-	display: flex;
-	align-items: stretch;
-	box-sizing: border-box;
-	padding: 6px 8px;
-	font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
-	font-size: 12px;
-	line-height: 1.25;
-	color: #0a0a0a;
-	background: rgb(255 255 255 / 85%);
-	backdrop-filter: saturate(180%) blur(20px);
-	-webkit-backdrop-filter: saturate(180%) blur(20px);
-	border-bottom: 1px solid rgb(0 0 0 / 8%);
-	box-shadow: 0 1px 2px rgb(0 0 0 / 4%);
-}
-
-.shell__pill {
-	display: inline-flex;
-	align-items: center;
-	padding: 8px 14px;
-	border: 0;
-	background: transparent;
-	border-radius: 999px;
-	text-decoration: none;
-	color: inherit;
-	font: inherit;
-	font-weight: 500;
-	white-space: nowrap;
-	transition: background 0.1s;
-	cursor: pointer;
-}
-
-.shell__pill:hover {
-	background: rgb(0 0 0 / 5%);
-}
-
-.shell__pill:active {
-	background: rgb(0 0 0 / 10%);
-}
-
-.shell__pill:focus-visible {
-	outline: 2px solid rgb(0 0 0 / 30%);
-	outline-offset: 1px;
-}
-
-.shell__divider {
-	flex-shrink: 0;
-	align-self: center;
-	width: 1px;
-	height: 16px;
-	background: rgb(0 0 0 / 10%);
-	margin: 0 2px;
-}
-
-.shell__label {
-	display: inline-flex;
-	align-items: center;
-	flex: 1 1 auto;
-	gap: 10px;
-	padding: 8px 14px;
-	overflow: hidden;
-	min-width: 0;
-}
-
-.shell__label-name {
-	font-weight: 600;
-	overflow: hidden;
-	text-overflow: ellipsis;
-	white-space: nowrap;
-}
-
-.shell__label-package {
-	font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
-	font-weight: 400;
-	font-size: 11px;
-	opacity: 0.55;
-	overflow: hidden;
-	text-overflow: ellipsis;
-	white-space: nowrap;
-}
-
-.manual-refresh-prompt {
-	position: fixed;
-	top: calc( var( --shell-height, 44px ) / 1.25 );
-	left: 50%;
-	z-index: 100000;
-	box-sizing: border-box;
-	padding: 8px 14px;
-	border: 1px solid #bfdbfe;
-	border-radius: 999px;
-	font: 600 12px/1.25 system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
-	color: #1d4ed8;
-	background: #dbeafe;
-	cursor: pointer;
-	opacity: 0;
-	pointer-events: none;
-	transform: translate(-50%, calc( -100% - var( --shell-height, 44px ) ) );
-	transition: transform 0.18s ease-out, opacity 0.18s ease-out, background 0.1s;
-}
-
-.manual-refresh-prompt--visible {
-	opacity: 1;
-	pointer-events: auto;
-	transform: translate(-50%, -50%);
-}
-
-.manual-refresh-prompt:hover {
-	background: #bfdbfe;
-}
-
-.manual-refresh-prompt:active {
-	background: #93c5fd;
-}
-
-.manual-refresh-prompt:focus-visible {
-	outline: 2px solid #2563eb;
-	outline-offset: 1px;
-}
-
-@media (max-width: 600px) {
-	.shell {
-		font-size: 11px;
-	}
-
-	.shell__label-package {
-		display: none;
-	}
-
-	.shell__label-name {
-		max-width: 20ch;
-	}
-}
-
-.shell-instructions {
-	--shell-instructions-width: min(420px, 45vw);
-	--shell-instructions-transition-duration: 0.18s;
-
-	position: fixed;
-	top: 44px;
-	right: 0;
-	bottom: 0;
-	z-index: 99998;
-	order: 2;
-	align-self: start;
-	flex: 0 0 0;
-	width: 0;
-	height: 0;
-	min-height: 0;
-	padding: 0;
-	border: 0;
-	background: #fff;
-	color: #0a0a0a;
-	font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
-	line-height: 1.6;
-	overflow: hidden;
-	transition:
-		flex-basis var(--shell-instructions-transition-duration) ease-out,
-		width var(--shell-instructions-transition-duration) ease-out;
-}
-
-.shell-instructions--open,
-.shell-instructions--closing {
-	align-self: stretch;
-	height: auto;
-	border-left: 1px solid rgb(0 0 0 / 8%);
-	box-shadow: -8px 0 24px rgb(0 0 0 / 8%);
-}
-
-.shell-instructions--open {
-	flex-basis: var(--shell-instructions-width);
-	width: var(--shell-instructions-width);
-}
-
-.shell-instructions__inner {
-	display: flex;
-	flex-direction: column;
-	width: var(--shell-instructions-width);
-	height: 100%;
-}
-
-.shell-instructions__header {
-	display: flex;
-	align-items: flex-start;
-	justify-content: space-between;
-	gap: 16px;
-	padding: 20px 24px;
-	border-bottom: 1px solid rgb(0 0 0 / 8%);
-	flex-shrink: 0;
-}
-
-.shell-instructions__titles {
-	min-width: 0;
-}
-
-.shell-instructions__title {
-	margin: 0 0 4px;
-	font-size: 18px;
-	font-weight: 700;
-	letter-spacing: -0.01em;
-	line-height: 1.3;
-	overflow: hidden;
-	text-overflow: ellipsis;
-	white-space: nowrap;
-}
-
-.shell-instructions__package {
-	font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
-	font-size: 12px;
-	color: #737373;
-}
-
-.shell-instructions__close {
-	flex-shrink: 0;
-	display: inline-flex;
-	align-items: center;
-	justify-content: center;
-	width: 32px;
-	height: 32px;
-	padding: 0;
-	border: 0;
-	border-radius: 8px;
-	background: transparent;
-	color: #737373;
-	cursor: pointer;
-	transition: background 0.1s, color 0.1s;
-}
-
-.shell-instructions__close:hover {
-	background: rgb(0 0 0 / 5%);
-	color: #0a0a0a;
-}
-
-.shell-instructions__close:focus-visible {
-	outline: 2px solid rgb(0 0 0 / 30%);
-	outline-offset: 1px;
-}
-
-.shell-instructions__body {
-	padding: 20px 24px 28px;
-	font-size: 14px;
-	overflow-y: auto;
-	min-height: 0;
-}
-
-.shell-instructions__body h1,
-.shell-instructions__body h2,
-.shell-instructions__body h3,
-.shell-instructions__body h4,
-.shell-instructions__body h5,
-.shell-instructions__body h6 {
-	margin: 24px 0 8px;
-	font-weight: 600;
-	letter-spacing: -0.01em;
-	line-height: 1.3;
-}
-
-.shell-instructions__body h1 { font-size: 20px; }
-.shell-instructions__body h2 { font-size: 17px; }
-.shell-instructions__body h3 { font-size: 15px; }
-.shell-instructions__body h4,
-.shell-instructions__body h5,
-.shell-instructions__body h6 { font-size: 14px; }
-
-.shell-instructions__body > :first-child { margin-top: 0; }
-.shell-instructions__body > :last-child { margin-bottom: 0; }
-
-.shell-instructions__body p {
-	margin: 8px 0;
-}
-
-.shell-instructions__body ul,
-.shell-instructions__body ol {
-	margin: 8px 0;
-	padding-left: 24px;
-}
-
-.shell-instructions__body li {
-	margin: 3px 0;
-}
-
-.shell-instructions__body code {
-	padding: 1px 6px;
-	border-radius: 4px;
-	background: #f0f0f0;
-	font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
-	font-size: 0.9em;
-}
-
-.shell-instructions__body pre {
-	margin: 12px 0;
-	padding: 12px 14px;
-	border-radius: 8px;
-	background: #f5f5f5;
-	overflow-x: auto;
-	font-size: 12px;
-	line-height: 1.5;
-}
-
-.shell-instructions__body pre code {
-	padding: 0;
-	background: transparent;
-	font-size: inherit;
-}
-
-.shell-instructions__body a {
-	color: #1d4ed8;
-	text-decoration: underline;
-	text-underline-offset: 2px;
-}
-
-.shell-instructions__body blockquote {
-	margin: 12px 0;
-	padding: 4px 14px;
-	border-left: 3px solid rgb(0 0 0 / 15%);
-	color: #525252;
-}
-
-.shell-instructions__body table {
-	margin: 12px 0;
-	border-collapse: collapse;
-	font-size: 13px;
-}
-
-.shell-instructions__body th,
-.shell-instructions__body td {
-	padding: 6px 10px;
-	border: 1px solid rgb(0 0 0 / 10%);
-	text-align: left;
-}
-
-.shell-instructions__body th {
-	background: #f5f5f5;
-	font-weight: 600;
-}
-
-.shell-instructions__body hr {
-	margin: 16px 0;
-	border: 0;
-	border-top: 1px solid rgb(0 0 0 / 10%);
-}
-
-@media (max-width: 800px) {
-	.shell-instructions {
-		--shell-instructions-width: min(360px, 70vw);
-	}
-}