@stll/folio-core 0.0.1-placeholder.0 → 0.1.1

package/dist/layout-painter/registry/types.d.ts

@@ -0,0 +1,61 @@
+import { FlowBlock, Fragment, ImageBlock, ImageMeasure, Measure, ParagraphBlock, ParagraphMeasure, TableBlock, TableMeasure, TextBoxBlock, TextBoxMeasure } from "../../layout-engine/types.js";
+import { RenderContext } from "../renderUtils.js";
+
+//#region src/layout-painter/registry/types.d.ts
+/**
+ * Resolve the concrete Fragment subtype for a given kind discriminator.
+ */
+type FragmentFor<TKind extends Fragment["kind"]> = Extract<Fragment, {
+  kind: TKind;
+}>;
+/**
+ * Maps Fragment kind -> concrete Block subtype. The block lookup table
+ * passes a `FlowBlock`; modules use this to narrow to the block they need
+ * without unsafe casts.
+ */
+type BlockFor<TKind extends Fragment["kind"]> = TKind extends "paragraph" ? ParagraphBlock : TKind extends "table" ? TableBlock : TKind extends "image" ? ImageBlock : TKind extends "textBox" ? TextBoxBlock : FlowBlock;
+/**
+ * Maps Fragment kind -> concrete Measure subtype. Same intent as `BlockFor`.
+ */
+type MeasureFor<TKind extends Fragment["kind"]> = TKind extends "paragraph" ? ParagraphMeasure : TKind extends "table" ? TableMeasure : TKind extends "image" ? ImageMeasure : TKind extends "textBox" ? TextBoxMeasure : Measure;
+/**
+ * Inputs handed to a feature module's render function.
+ */
+type FeatureRenderInput<TKind extends Fragment["kind"]> = {
+  fragment: FragmentFor<TKind>;
+  block: BlockFor<TKind>;
+  measure: MeasureFor<TKind>;
+  context: RenderContext;
+  doc: Document;
+};
+/**
+ * One renderer for one OOXML fragment kind. Pure — no instance state.
+ */
+type FeatureModule<TKind extends Fragment["kind"] = Fragment["kind"]> = {
+  readonly kind: TKind;
+  render: (input: FeatureRenderInput<TKind>) => HTMLElement;
+};
+/**
+ * Dispatch input: caller hands the registry the still-untyped fragment plus
+ * its associated block/measure, and the registry narrows by kind.
+ */
+type FeatureDispatchInput = {
+  fragment: Fragment;
+  block: FlowBlock | undefined;
+  measure: Measure | undefined;
+  context: RenderContext;
+  doc: Document;
+};
+/**
+ * Fallback hook invoked when no module matches the fragment's kind (or when
+ * block/measure are missing for a fragment that needs them). Mirrors the
+ * existing `renderFragment` placeholder behaviour so partial registries stay
+ * safe at runtime.
+ */
+type FeatureFallback = (input: {
+  fragment: Fragment;
+  context: RenderContext;
+  doc: Document;
+}) => HTMLElement;
+//#endregion
+export { BlockFor, FeatureDispatchInput, FeatureFallback, FeatureModule, FeatureRenderInput, FragmentFor, MeasureFor };

package/dist/layout-painter/renderFragment.d.ts

@@ -0,0 +1,32 @@
+import { Fragment } from "../layout-engine/types.js";
+import { RenderContext } from "./renderUtils.js";
+
+//#region src/layout-painter/renderFragment.d.ts
+/**
+ * CSS class names for fragment elements
+ */
+declare const FRAGMENT_CLASS_NAMES: {
+  fragment: string;
+  paragraph: string;
+  table: string;
+  image: string;
+  line: string;
+  run: string;
+};
+/**
+ * Options for rendering fragments
+ */
+type RenderFragmentOptions = {
+  /** Document to create elements in */document?: Document;
+};
+/**
+ * Render a fragment to DOM
+ *
+ * @param fragment - The fragment to render
+ * @param context - Rendering context
+ * @param options - Rendering options
+ * @returns The fragment DOM element
+ */
+declare function renderFragment(fragment: Fragment, context: RenderContext, options?: RenderFragmentOptions): HTMLElement;
+//#endregion
+export { FRAGMENT_CLASS_NAMES, RenderFragmentOptions, renderFragment };

package/dist/layout-painter/renderFragment.js

@@ -0,0 +1,114 @@
+import { applySdtDataAttrs } from "./sdtBoundary.js";
+//#region src/layout-painter/renderFragment.ts
+/**
+* CSS class names for fragment elements
+*/
+const FRAGMENT_CLASS_NAMES = {
+	fragment: "layout-fragment",
+	paragraph: "layout-fragment-paragraph",
+	table: "layout-fragment-table",
+	image: "layout-fragment-image",
+	line: "layout-line",
+	run: "layout-run"
+};
+/**
+* Check if fragment is a paragraph fragment
+*/
+function isParagraphFragment(fragment) {
+	return fragment.kind === "paragraph";
+}
+/**
+* Check if fragment is a table fragment
+*/
+function isTableFragment(fragment) {
+	return fragment.kind === "table";
+}
+/**
+* Check if fragment is an image fragment
+*/
+function isImageFragment(fragment) {
+	return fragment.kind === "image";
+}
+/**
+* Apply base fragment styles
+*/
+function applyBaseFragmentStyles(element) {
+	element.style.position = "absolute";
+	element.style.overflow = "hidden";
+}
+/**
+* Render a paragraph fragment
+*
+* Note: The actual lines/runs are rendered separately since we need
+* access to the original ParagraphBlock and ParagraphMeasure.
+* This creates a placeholder that will be filled by the full painter.
+*/
+function renderParagraphFragmentPlaceholder(fragment, _context, doc) {
+	const el = doc.createElement("div");
+	el.className = `${FRAGMENT_CLASS_NAMES.fragment} ${FRAGMENT_CLASS_NAMES.paragraph}`;
+	applyBaseFragmentStyles(el);
+	el.dataset["blockId"] = String(fragment.blockId);
+	el.dataset["fromLine"] = String(fragment.fromLine);
+	el.dataset["toLine"] = String(fragment.toLine);
+	if (fragment.pmStart !== void 0) el.dataset["pmStart"] = String(fragment.pmStart);
+	if (fragment.pmEnd !== void 0) el.dataset["pmEnd"] = String(fragment.pmEnd);
+	if (fragment.continuesFromPrev) el.dataset["continuesFromPrev"] = "true";
+	if (fragment.continuesOnNext) el.dataset["continuesOnNext"] = "true";
+	applySdtDataAttrs(el, fragment.sdtGroups);
+	return el;
+}
+/**
+* Render a table fragment
+*
+* Note: Similar to paragraphs, actual table rendering requires
+* access to the TableBlock. This creates a placeholder.
+*/
+function renderTableFragmentPlaceholder(fragment, _context, doc) {
+	const el = doc.createElement("div");
+	el.className = `${FRAGMENT_CLASS_NAMES.fragment} ${FRAGMENT_CLASS_NAMES.table}`;
+	applyBaseFragmentStyles(el);
+	el.dataset["blockId"] = String(fragment.blockId);
+	el.dataset["fromRow"] = String(fragment.fromRow);
+	el.dataset["toRow"] = String(fragment.toRow);
+	if (fragment.pmStart !== void 0) el.dataset["pmStart"] = String(fragment.pmStart);
+	if (fragment.pmEnd !== void 0) el.dataset["pmEnd"] = String(fragment.pmEnd);
+	applySdtDataAttrs(el, fragment.sdtGroups);
+	return el;
+}
+/**
+* Render an image fragment
+*/
+function renderImageFragmentPlaceholder(fragment, _context, doc) {
+	const el = doc.createElement("div");
+	el.className = `${FRAGMENT_CLASS_NAMES.fragment} ${FRAGMENT_CLASS_NAMES.image}`;
+	applyBaseFragmentStyles(el);
+	el.dataset["blockId"] = String(fragment.blockId);
+	if (fragment.pmStart !== void 0) el.dataset["pmStart"] = String(fragment.pmStart);
+	if (fragment.pmEnd !== void 0) el.dataset["pmEnd"] = String(fragment.pmEnd);
+	if (fragment.isAnchored) el.dataset["anchored"] = "true";
+	if (fragment.zIndex !== void 0) el.style.zIndex = String(fragment.zIndex);
+	return el;
+}
+/**
+* Render a fragment to DOM
+*
+* @param fragment - The fragment to render
+* @param context - Rendering context
+* @param options - Rendering options
+* @returns The fragment DOM element
+*/
+function renderFragment(fragment, context, options = {}) {
+	const doc = options.document ?? document;
+	if (isParagraphFragment(fragment)) return renderParagraphFragmentPlaceholder(fragment, context, doc);
+	if (isTableFragment(fragment)) return renderTableFragmentPlaceholder(fragment, context, doc);
+	if (isImageFragment(fragment)) return renderImageFragmentPlaceholder(fragment, context, doc);
+	const el = doc.createElement("div");
+	el.className = FRAGMENT_CLASS_NAMES.fragment;
+	applyBaseFragmentStyles(el);
+	const unknownFragment = fragment;
+	if (unknownFragment.blockId !== void 0) el.dataset["blockId"] = unknownFragment.blockId;
+	if (unknownFragment.kind) el.dataset["kind"] = unknownFragment.kind;
+	return el;
+}
+//#endregion
+export { FRAGMENT_CLASS_NAMES, renderFragment };

package/dist/layout-painter/renderImage.d.ts

@@ -0,0 +1,88 @@
+import { ImageBlock, ImageFragment, ImageMeasure } from "../layout-engine/types.js";
+import { RenderContext } from "./renderUtils.js";
+
+//#region src/layout-painter/renderImage.d.ts
+/**
+ * CSS class names for image elements
+ */
+declare const IMAGE_CLASS_NAMES: {
+  image: string;
+  imageAnchored: string;
+};
+/**
+ * Structural shape required to apply Word's per-image visual attributes:
+ * `wp:srcRect` crop fractions and `a:alphaModFix` opacity. `ImageRun` and
+ * `ImageBlock` both satisfy this, so callers don't need an adapter.
+ */
+type ImageVisualAttrs = {
+  opacity?: number;
+  cropTop?: number;
+  cropRight?: number;
+  cropBottom?: number;
+  cropLeft?: number;
+};
+/**
+ * True when any visual attribute is set. Cheap call-site guard so the no-op
+ * common case skips the helper call.
+ *
+ * IMPORTANT: ProseMirror schema attrs default to `null`, not `undefined`,
+ * and a `null` survives `as number | undefined` casts in the layout bridge.
+ * Use `!= null` rather than `!== undefined` so default-null opacity / crop
+ * fields are not read as `0` (`null < 1` is `true`, `Math.max(0, null)` is
+ * `0`) — that bug otherwise hides every plain image behind `opacity: 0`.
+ */
+declare function hasImageVisualAttrs(v: ImageVisualAttrs): boolean;
+/**
+ * Apply Word's `<a:srcRect>` crop to an `<img>` whose parent already has
+ * `overflow: hidden` and is sized to the *visible* (cropped) dimensions
+ * (this matches `wp:extent` semantics: in Word the extent is the cropped
+ * frame, with `<a:stretch><a:fillRect/>` stretching the cropped source to
+ * fill it).
+ *
+ * Implementation: scale the `<img>` up so the visible region fills the
+ * parent, then shift it by the negative crop offsets so only that region
+ * remains in view. A naive `clip-path: inset(...)` is wrong here — it would
+ * leave the bitmap rendered at full extent size (so the wrong region shows)
+ * and only mask the rest, producing a squished image with blank bands.
+ *
+ * `fw = 1/(1-left-right)` and `fh = 1/(1-top-bottom)` are the inverse
+ * remaining-fractions; multiplying by 100% gives the upscaled width/height
+ * so the cropped slice exactly covers the parent.
+ *
+ * Caller should gate with `hasImageVisualAttrs(v)` to avoid the function
+ * call for plain images.
+ */
+declare function applyImageVisualAttrs(img: HTMLImageElement, v: ImageVisualAttrs): void;
+/**
+ * Create an inline-block `<span>` wrapper sized to the visible (cropped)
+ * dimensions with `overflow: hidden`, then size+scale+shift the `<img>`
+ * inside it so only the cropped region of the bitmap is visible. See
+ * `applyImageVisualAttrs` for the geometry rationale.
+ *
+ * Use this for inline runs and block images where the painter does not
+ * already provide an overflow-clipped container.
+ */
+declare function wrapImageWithCrop(img: HTMLImageElement, v: ImageVisualAttrs, doc: Document, outerStyle: {
+  display: "inline-block" | "block";
+  widthPx: number;
+  heightPx: number;
+}): HTMLElement;
+/**
+ * Options for rendering an image fragment
+ */
+type RenderImageFragmentOptions = {
+  document?: Document;
+};
+/**
+ * Render an image fragment to DOM
+ *
+ * @param fragment - The image fragment to render
+ * @param block - The full image block
+ * @param measure - The image measure
+ * @param context - Rendering context
+ * @param options - Rendering options
+ * @returns The image DOM element
+ */
+declare function renderImageFragment(fragment: ImageFragment, block: ImageBlock, _measure: ImageMeasure, _context: RenderContext, options?: RenderImageFragmentOptions): HTMLElement;
+//#endregion
+export { IMAGE_CLASS_NAMES, ImageVisualAttrs, RenderImageFragmentOptions, applyImageVisualAttrs, hasImageVisualAttrs, renderImageFragment, wrapImageWithCrop };

package/dist/layout-painter/renderImage.js

@@ -0,0 +1,130 @@
+//#region src/layout-painter/renderImage.ts
+/**
+* CSS class names for image elements
+*/
+const IMAGE_CLASS_NAMES = {
+	image: "layout-image",
+	imageAnchored: "layout-image-anchored"
+};
+/**
+* True when any visual attribute is set. Cheap call-site guard so the no-op
+* common case skips the helper call.
+*
+* IMPORTANT: ProseMirror schema attrs default to `null`, not `undefined`,
+* and a `null` survives `as number | undefined` casts in the layout bridge.
+* Use `!= null` rather than `!== undefined` so default-null opacity / crop
+* fields are not read as `0` (`null < 1` is `true`, `Math.max(0, null)` is
+* `0`) — that bug otherwise hides every plain image behind `opacity: 0`.
+*/
+function hasImageVisualAttrs(v) {
+	if (v.opacity != null && v.opacity < 1) return true;
+	return Boolean(v.cropTop || v.cropRight || v.cropBottom || v.cropLeft);
+}
+/**
+* Apply Word's `<a:srcRect>` crop to an `<img>` whose parent already has
+* `overflow: hidden` and is sized to the *visible* (cropped) dimensions
+* (this matches `wp:extent` semantics: in Word the extent is the cropped
+* frame, with `<a:stretch><a:fillRect/>` stretching the cropped source to
+* fill it).
+*
+* Implementation: scale the `<img>` up so the visible region fills the
+* parent, then shift it by the negative crop offsets so only that region
+* remains in view. A naive `clip-path: inset(...)` is wrong here — it would
+* leave the bitmap rendered at full extent size (so the wrong region shows)
+* and only mask the rest, producing a squished image with blank bands.
+*
+* `fw = 1/(1-left-right)` and `fh = 1/(1-top-bottom)` are the inverse
+* remaining-fractions; multiplying by 100% gives the upscaled width/height
+* so the cropped slice exactly covers the parent.
+*
+* Caller should gate with `hasImageVisualAttrs(v)` to avoid the function
+* call for plain images.
+*/
+function applyImageVisualAttrs(img, v) {
+	if (v.opacity != null && v.opacity < 1) img.style.opacity = String(Math.max(0, v.opacity));
+	const top = v.cropTop ?? 0;
+	const right = v.cropRight ?? 0;
+	const bottom = v.cropBottom ?? 0;
+	const left = v.cropLeft ?? 0;
+	if (!(top || right || bottom || left)) return;
+	const remainingW = 1 - left - right;
+	const remainingH = 1 - top - bottom;
+	if (remainingW <= 0 || remainingH <= 0) return;
+	const fw = 1 / remainingW;
+	const fh = 1 / remainingH;
+	img.style.width = `${fw * 100}%`;
+	img.style.height = `${fh * 100}%`;
+	img.style.marginLeft = `${-left * fw * 100}%`;
+	img.style.marginTop = `${-top * fh * 100}%`;
+	img.style.objectFit = "fill";
+}
+/**
+* Create an inline-block `<span>` wrapper sized to the visible (cropped)
+* dimensions with `overflow: hidden`, then size+scale+shift the `<img>`
+* inside it so only the cropped region of the bitmap is visible. See
+* `applyImageVisualAttrs` for the geometry rationale.
+*
+* Use this for inline runs and block images where the painter does not
+* already provide an overflow-clipped container.
+*/
+function wrapImageWithCrop(img, v, doc, outerStyle) {
+	const wrapper = doc.createElement("span");
+	wrapper.style.display = outerStyle.display;
+	wrapper.style.overflow = "hidden";
+	wrapper.style.width = `${outerStyle.widthPx}px`;
+	wrapper.style.height = `${outerStyle.heightPx}px`;
+	img.style.width = "100%";
+	img.style.height = "100%";
+	applyImageVisualAttrs(img, v);
+	wrapper.append(img);
+	return wrapper;
+}
+/**
+* Render an image fragment to DOM
+*
+* @param fragment - The image fragment to render
+* @param block - The full image block
+* @param measure - The image measure
+* @param context - Rendering context
+* @param options - Rendering options
+* @returns The image DOM element
+*/
+function renderImageFragment(fragment, block, _measure, _context, options = {}) {
+	const doc = options.document ?? document;
+	const containerEl = doc.createElement("div");
+	containerEl.className = IMAGE_CLASS_NAMES.image;
+	if (fragment.isAnchored) containerEl.classList.add(IMAGE_CLASS_NAMES.imageAnchored);
+	containerEl.style.position = "absolute";
+	containerEl.style.width = `${fragment.width}px`;
+	containerEl.style.height = `${fragment.height}px`;
+	containerEl.style.overflow = "hidden";
+	if (fragment.zIndex !== void 0) containerEl.style.zIndex = String(fragment.zIndex);
+	if (block.anchor?.behindDoc) containerEl.style.zIndex = "-1";
+	containerEl.dataset["blockId"] = String(fragment.blockId);
+	if (fragment.pmStart !== void 0) containerEl.dataset["pmStart"] = String(fragment.pmStart);
+	if (fragment.pmEnd !== void 0) containerEl.dataset["pmEnd"] = String(fragment.pmEnd);
+	const imgEl = doc.createElement("img");
+	imgEl.src = block.src;
+	imgEl.alt = block.alt ?? "";
+	imgEl.style.width = "100%";
+	imgEl.style.height = "100%";
+	imgEl.style.objectFit = "contain";
+	imgEl.style.display = "block";
+	if (block.transform) imgEl.style.transform = block.transform;
+	if (hasImageVisualAttrs(block)) applyImageVisualAttrs(imgEl, block);
+	imgEl.draggable = false;
+	if (block.hlinkHref) {
+		const linkEl = doc.createElement("a");
+		linkEl.href = block.hlinkHref;
+		linkEl.target = "_blank";
+		linkEl.rel = "noopener noreferrer";
+		linkEl.style.display = "block";
+		linkEl.style.width = "100%";
+		linkEl.style.height = "100%";
+		linkEl.append(imgEl);
+		containerEl.append(linkEl);
+	} else containerEl.append(imgEl);
+	return containerEl;
+}
+//#endregion
+export { IMAGE_CLASS_NAMES, applyImageVisualAttrs, hasImageVisualAttrs, renderImageFragment, wrapImageWithCrop };