@marianmeres/stuic 3.111.0 → 3.112.0

package/dist/components/MarkdownEditor/MarkdownEditor.svelte

@@ -112,6 +112,23 @@
 		 * (any `window.prompt`-compatible sync/async function works).
 		 */
 		prompt?: PromptFn;
+		/**
+		 * Caps the editing surface height so a long document scrolls *inside* the
+		 * surface instead of growing the editor (which would push the toolbar out
+		 * of view). `number` → pixels; `string` → any CSS length (`"40rem"`,
+		 * `"60vh"`, `"min(40rem,50vh)"`). Defaults to `32rem` (themeable via
+		 * `--stuic-markdown-editor-max-height`). The surface is additionally capped
+		 * to the parent's available height when {@link capToParent} is on — the
+		 * smaller limit wins.
+		 */
+		maxHeight?: number | string;
+		/**
+		 * Also cap the editing surface to the height available in the parent
+		 * container (measured at runtime), so the editor never overflows a
+		 * height-constrained parent. Default `true`. Set `false` to rely solely on
+		 * {@link maxHeight}.
+		 */
+		capToParent?: boolean;
 		/** Show the WYSIWYG/Source mode toggle. Default `true`. */
 		showModeToggle?: boolean;
 		/** Label for the toggle when in WYSIWYG mode (switches to source). */
@@ -165,6 +182,12 @@
 	} from "../../icons/index.js";
 	import InputWrap from "../Input/_internal/InputWrap.svelte";
 	import type { EditorCommands, EditorHandle, PromptFn } from "./_internal/types.js";
+	import {
+		computeParentAvailable,
+		DEFAULT_MAX_HEIGHT_VAR,
+		maxHeightToCss,
+		surfaceMaxHeight,
+	} from "./_internal/max-height.js";
 	import "./index.css";
 
 	// Default URL prompt for link/image — the native `window.prompt`. Opt into
@@ -227,6 +250,8 @@
 		autoSourceOnMobile = true,
 		mobileQuery = "(pointer: coarse) and (max-width: 640px)",
 		prompt = defaultPrompt,
+		maxHeight,
+		capToParent = true,
 		showModeToggle = true,
 		sourceLabel = "Source",
 		previewLabel = "Preview",
@@ -285,6 +310,78 @@
 		input = host;
 	});
 
+	// --- Surface max-height ---------------------------------------------------
+	// Cap the editing surface so a long document scrolls internally instead of
+	// growing the editor (which scrolls the toolbar out of view). The base cap is
+	// the `maxHeight` prop (funneled into the CSS var so the surface rule + the
+	// min() below both see it) or `32rem`; `capToParent` further caps it to the
+	// parent's measured available height. `min()` picks the smaller limit.
+
+	// Funnel an explicit `maxHeight` into the themeable CSS var on the root.
+	const maxHeightVar = $derived.by(() => {
+		const css = maxHeightToCss(maxHeight);
+		return css ? `--stuic-markdown-editor-max-height: ${css};` : undefined;
+	});
+
+	// Measured parent-available height (px), or null when capping is off / not
+	// yet measured / the parent is unconstrained — then the CSS default applies.
+	let parentAvailable = $state<number | null>(null);
+
+	// Inline surface `max-height`; undefined falls back to the CSS rule default.
+	const surfaceMaxHeightCss = $derived(
+		capToParent && parentAvailable != null
+			? surfaceMaxHeight(DEFAULT_MAX_HEIGHT_VAR, parentAvailable)
+			: undefined
+	);
+
+	$effect(() => {
+		if (!capToParent || !host || typeof ResizeObserver === "undefined") {
+			parentAvailable = null;
+			return;
+		}
+		const surface = host;
+		// Measure against the parent of the whole field (InputWrap's root), which
+		// is the consumer's container — that is the "parent" whose height we cap to.
+		const root = (surface.closest(".stuic-input") as HTMLElement | null) ?? surface;
+		const parent = root.parentElement;
+		if (!parent) {
+			parentAvailable = null;
+			return;
+		}
+
+		const measure = () => {
+			const cs = getComputedStyle(parent);
+			const next = computeParentAvailable({
+				fromTop: surface.getBoundingClientRect().top,
+				parentBottom: parent.getBoundingClientRect().bottom,
+				parentBorderBottom: parseFloat(cs.borderBottomWidth) || 0,
+				parentPaddingBottom: parseFloat(cs.paddingBottom) || 0,
+			});
+			// `untrack` the read of `parentAvailable`: the initial measure() runs
+			// inside this effect, and tracking its own output would tear down and
+			// rebuild the observer on every measurement. The threshold also guards
+			// against sub-pixel ResizeObserver feedback loops.
+			const prev = untrack(() => parentAvailable);
+			if (next == null) {
+				if (prev !== null) parentAvailable = null;
+			} else if (prev == null || Math.abs(next - prev) > 1) {
+				parentAvailable = next;
+			}
+		};
+
+		measure();
+		const ro = new ResizeObserver(measure);
+		ro.observe(parent);
+		// Observe the field root too, so the surface re-measures when content above
+		// it reflows (label wraps, description expands, validation message appears).
+		ro.observe(root);
+		window.addEventListener("resize", measure);
+		return () => {
+			ro.disconnect();
+			window.removeEventListener("resize", measure);
+		};
+	});
+
 	// Handle to whichever backend is currently mounted (null while (re)loading).
 	let activeHandle = $state<EditorHandle | undefined>();
 
@@ -464,6 +561,7 @@
 		class:disabled
 		data-size={renderSize}
 		data-mode={mode}
+		style={maxHeightVar}
 	>
 		{#if toolbarItems.length || showModeToggle}
 			<div class={twMerge("stuic-markdown-editor-bar", classToolbar)}>
@@ -511,6 +609,7 @@
 		<div
 			bind:this={host}
 			class="stuic-markdown-editor-surface"
+			style:max-height={surfaceMaxHeightCss}
 			onfocusout={handleFocusOut}
 			role="textbox"
 			aria-multiline="true"

package/dist/components/MarkdownEditor/MarkdownEditor.svelte.d.ts

@@ -54,6 +54,23 @@ export interface Props extends InputWrapClassProps {
      * (any `window.prompt`-compatible sync/async function works).
      */
     prompt?: PromptFn;
+    /**
+     * Caps the editing surface height so a long document scrolls *inside* the
+     * surface instead of growing the editor (which would push the toolbar out
+     * of view). `number` → pixels; `string` → any CSS length (`"40rem"`,
+     * `"60vh"`, `"min(40rem,50vh)"`). Defaults to `32rem` (themeable via
+     * `--stuic-markdown-editor-max-height`). The surface is additionally capped
+     * to the parent's available height when {@link capToParent} is on — the
+     * smaller limit wins.
+     */
+    maxHeight?: number | string;
+    /**
+     * Also cap the editing surface to the height available in the parent
+     * container (measured at runtime), so the editor never overflows a
+     * height-constrained parent. Default `true`. Set `false` to rely solely on
+     * {@link maxHeight}.
+     */
+    capToParent?: boolean;
     /** Show the WYSIWYG/Source mode toggle. Default `true`. */
     showModeToggle?: boolean;
     /** Label for the toggle when in WYSIWYG mode (switches to source). */

package/dist/components/MarkdownEditor/README.md

@@ -60,6 +60,8 @@ Bind the component instance to access:
 | `validate`       | `boolean \| ValidateOptions` | –           | Pass a `customValidator` to validate markdown                       |
 | `renderSize`     | `"sm" \| "md" \| "lg"`       | `"md"`      |                                                                     |
 | `toolbar`        | `boolean \| ToolbarItem[]`   | `true`      | `true` = default toolbar, `false` = none, or an ordered button list |
+| `maxHeight`      | `number \| string`           | `32rem`     | Surface height cap (`number` = px). Long docs scroll internally     |
+| `capToParent`    | `boolean`                    | `true`      | Also cap the surface to the parent's available height               |
 | `showModeToggle` | `boolean`                    | `true`      | Show the WYSIWYG/source toggle                                      |
 | `name`           | `string`                     | –           | Hidden input name for form submission                               |
 
@@ -95,6 +97,33 @@ Available items: `bold`, `italic`, `heading1`, `heading2`, `heading3`, `link`,
 `hardBreak`, `undo`, `redo`, and `"|"` (separator). The default layout is
 exported as `DEFAULT_TOOLBAR`.
 
+### Height & scrolling
+
+A long document never grows the editor unbounded (which would scroll the toolbar
+out of view). The editing **surface** has a finite max height and scrolls
+internally instead:
+
+- **Fixed cap** — `maxHeight` (`number` → px, or any CSS length string like
+  `"40rem"` / `"60vh"`), defaulting to `32rem` (themeable via
+  `--stuic-markdown-editor-max-height`).
+- **Parent cap** — with `capToParent` on (default), the surface is _also_ capped
+  to the height available in the parent container, measured at runtime. The
+  **smaller** of the two limits wins, so the editor fills — but never overflows —
+  a height-constrained parent (e.g. a flex column, modal body, or split pane).
+
+```svelte
+<!-- explicit fixed cap; ignore the parent -->
+<MarkdownEditor bind:value maxHeight="20rem" capToParent={false} />
+
+<!-- fill a height-constrained pane, scrolling internally past its available height -->
+<div style="height: 60vh; display: flex; flex-direction: column;">
+	<MarkdownEditor bind:value maxHeight="100vh" />
+</div>
+```
+
+The minimum height (`--stuic-markdown-editor-min-height`, `12rem` for `md`) still
+applies, so the surface never collapses below a usable editing area.
+
 ### Link / image URL prompt
 
 By default the link and image buttons ask for a URL via the native
@@ -146,7 +175,7 @@ input/global tokens:
 --stuic-markdown-editor-border-focus
 --stuic-markdown-editor-bg
 --stuic-markdown-editor-min-height  /* default 12rem (9/16rem for sm/lg) */
---stuic-markdown-editor-max-height
+--stuic-markdown-editor-max-height  /* default 32rem; see "Height & scrolling" */
 --stuic-markdown-editor-font-size
 --stuic-markdown-editor-font-mono
 --stuic-markdown-editor-code-bg

package/dist/components/MarkdownEditor/_internal/max-height.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Pure helpers for the MarkdownEditor's editing-surface max-height resolution.
+ *
+ * Deliberately framework-free (no DOM, no Svelte) so the height-capping logic is
+ * unit-testable without a browser/layout engine. `MarkdownEditor.svelte` does the
+ * actual DOM measurement and feeds the resulting numbers through these helpers.
+ */
+/**
+ * Base cap applied to the editing surface, as a CSS expression. Reads the
+ * themeable `--stuic-markdown-editor-max-height` custom property, falling back
+ * to `32rem`. The `32rem` fallback is kept in sync with the same value in
+ * `index.css` (`.stuic-markdown-editor-surface`).
+ */
+export declare const DEFAULT_MAX_HEIGHT_VAR = "var(--stuic-markdown-editor-max-height, 32rem)";
+/**
+ * Normalize a `maxHeight` prop value into a CSS length.
+ * - `number` → pixels (`240` → `"240px"`)
+ * - `string` → used verbatim (any CSS length: `"40rem"`, `"60vh"`, `"min(40rem,50vh)"`)
+ * - `null` / `undefined` / empty / non-finite → `null` (caller uses the default)
+ */
+export declare function maxHeightToCss(value: number | string | null | undefined): string | null;
+/**
+ * Combine the configured cap (`base`, a CSS length/expression) with the measured
+ * parent-available height. When a positive `parentAvailablePx` is given the
+ * surface is capped to the smaller of the two via CSS `min()`, so it never
+ * overflows a height-constrained parent. Otherwise the base cap is returned
+ * unchanged.
+ */
+export declare function surfaceMaxHeight(base: string, parentAvailablePx: number | null): string;
+/** Inputs for {@link computeParentAvailable}, in CSS px (viewport coords for tops/bottoms). */
+export interface ParentAvailableInput {
+    /** Viewport-relative top of the element we measure from (the editing surface). */
+    fromTop: number;
+    /** Viewport-relative bottom of the parent's border box (`getBoundingClientRect().bottom`). */
+    parentBottom: number;
+    /** Parent computed `border-bottom-width` in px. Default `0`. */
+    parentBorderBottom?: number;
+    /** Parent computed `padding-bottom` in px. Default `0`. */
+    parentPaddingBottom?: number;
+    /** Extra breathing room to leave below the editor, in px. Default `0`. */
+    bottomGap?: number;
+}
+/**
+ * Compute the vertical space available to the editor inside its parent: the
+ * distance from `fromTop` down to the bottom of the parent's content box, less
+ * an optional `bottomGap`.
+ *
+ * Returns `null` when the result is not positive — the parent is smaller than
+ * the editor's offset (e.g. not laid out yet), so no meaningful cap can be
+ * derived and the caller should fall back to the configured base.
+ *
+ * Note: in an auto-height (content-sized) parent this naturally returns roughly
+ * the editor's own height, so `surfaceMaxHeight(base, …)` resolves to the base
+ * cap and the parent constraint only bites when the parent is genuinely smaller.
+ */
+export declare function computeParentAvailable(input: ParentAvailableInput): number | null;

package/dist/components/MarkdownEditor/_internal/max-height.js

@@ -0,0 +1,60 @@
+/**
+ * Pure helpers for the MarkdownEditor's editing-surface max-height resolution.
+ *
+ * Deliberately framework-free (no DOM, no Svelte) so the height-capping logic is
+ * unit-testable without a browser/layout engine. `MarkdownEditor.svelte` does the
+ * actual DOM measurement and feeds the resulting numbers through these helpers.
+ */
+/**
+ * Base cap applied to the editing surface, as a CSS expression. Reads the
+ * themeable `--stuic-markdown-editor-max-height` custom property, falling back
+ * to `32rem`. The `32rem` fallback is kept in sync with the same value in
+ * `index.css` (`.stuic-markdown-editor-surface`).
+ */
+export const DEFAULT_MAX_HEIGHT_VAR = "var(--stuic-markdown-editor-max-height, 32rem)";
+/**
+ * Normalize a `maxHeight` prop value into a CSS length.
+ * - `number` → pixels (`240` → `"240px"`)
+ * - `string` → used verbatim (any CSS length: `"40rem"`, `"60vh"`, `"min(40rem,50vh)"`)
+ * - `null` / `undefined` / empty / non-finite → `null` (caller uses the default)
+ */
+export function maxHeightToCss(value) {
+    if (value == null)
+        return null;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? `${value}px` : null;
+    const trimmed = value.trim();
+    return trimmed.length ? trimmed : null;
+}
+/**
+ * Combine the configured cap (`base`, a CSS length/expression) with the measured
+ * parent-available height. When a positive `parentAvailablePx` is given the
+ * surface is capped to the smaller of the two via CSS `min()`, so it never
+ * overflows a height-constrained parent. Otherwise the base cap is returned
+ * unchanged.
+ */
+export function surfaceMaxHeight(base, parentAvailablePx) {
+    if (parentAvailablePx != null && parentAvailablePx > 0) {
+        return `min(${base}, ${Math.round(parentAvailablePx)}px)`;
+    }
+    return base;
+}
+/**
+ * Compute the vertical space available to the editor inside its parent: the
+ * distance from `fromTop` down to the bottom of the parent's content box, less
+ * an optional `bottomGap`.
+ *
+ * Returns `null` when the result is not positive — the parent is smaller than
+ * the editor's offset (e.g. not laid out yet), so no meaningful cap can be
+ * derived and the caller should fall back to the configured base.
+ *
+ * Note: in an auto-height (content-sized) parent this naturally returns roughly
+ * the editor's own height, so `surfaceMaxHeight(base, …)` resolves to the base
+ * cap and the parent constraint only bites when the parent is genuinely smaller.
+ */
+export function computeParentAvailable(input) {
+    const { fromTop, parentBottom, parentBorderBottom = 0, parentPaddingBottom = 0, bottomGap = 0, } = input;
+    const contentBottom = parentBottom - parentBorderBottom - parentPaddingBottom;
+    const available = contentBottom - fromTop - bottomGap;
+    return available > 0 ? Math.floor(available) : null;
+}

package/dist/components/MarkdownEditor/index.css

@@ -157,7 +157,12 @@
 	flex: 1;
 	min-width: 0;
 	min-height: var(--_min-height);
-	max-height: var(--stuic-markdown-editor-max-height, none);
+	/* A finite default cap so a long document scrolls INSIDE the surface instead
+	   of growing the editor unbounded (which scrolls the toolbar out of view).
+	   `32rem` is kept in sync with DEFAULT_MAX_HEIGHT_VAR in _internal/max-height.ts.
+	   The component may narrow this further (inline `max-height`) to the parent's
+	   available height — see the `maxHeight` / `capToParent` props. */
+	max-height: var(--stuic-markdown-editor-max-height, 32rem);
 	overflow: auto;
 	padding: var(--_pad-y) var(--_pad-x);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/stuic",
-	"version": "3.111.0",
+	"version": "3.112.0",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && pnpm run prepack",