simple-module-pagebuilder 0.0.2__tar.gz → 0.0.3__tar.gz

{simple_module_pagebuilder-0.0.2 → simple_module_pagebuilder-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simple_module_pagebuilder
-Version: 0.0.2
+Version: 0.0.3
 Summary: Drag-and-drop visual page builder for simple_module apps
 Project-URL: Repository, https://github.com/antosubash/simple_module_python_modules
 Author-email: Anto Subash <antosubash@live.com>

{simple_module_pagebuilder-0.0.2 → simple_module_pagebuilder-0.0.3}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simple-module-py/pagebuilder",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "private": true,
   "description": "Frontend assets for the PageBuilder module",
   "peerDependencies": {

simple_module_pagebuilder-0.0.3/pagebuilder/components/blocks/Image.test.tsx

@@ -0,0 +1,94 @@
+import type { ReactElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+
+import { ImageBlock } from './Image';
+
+// Puck passes its own `id`/`puck` props alongside the authored ones; the block
+// reads none of them, so these tests supply the authored props alone.
+const Image = ImageBlock.render as unknown as (props: Record<string, unknown>) => ReactElement;
+
+const BASE = {
+  ...ImageBlock.defaultProps,
+  src: '/media/pagebuilder/atlas-map.jpg',
+  alt: 'The Global Canopy Atlas interactive map',
+};
+
+function html(props: Record<string, unknown> = {}): string {
+  return renderToStaticMarkup(<Image {...BASE} {...props} />);
+}
+
+describe('ImageBlock caption', () => {
+  it('offers a Caption field in the inspector', () => {
+    expect(ImageBlock.fields?.caption).toEqual({ type: 'text', label: 'Caption' });
+  });
+
+  it('defaults to no caption', () => {
+    expect(ImageBlock.defaultProps?.caption).toBe('');
+  });
+
+  it('renders the caption in a figcaption inside a figure', () => {
+    const markup = html({ caption: 'Image caption goes here, if CMS field is populated' });
+    expect(markup).toContain('<figure');
+    expect(markup).toContain('<figcaption');
+    expect(markup).toContain('Image caption goes here, if CMS field is populated');
+  });
+
+  it('takes the caption’s colour and metrics from the design pack', () => {
+    // A tenant restyles captions by overriding tokens, not by patching this
+    // block — same contract the widget set gives the rest of the page.
+    const markup = html({ caption: 'A caption' });
+    expect(markup).toContain('--pb-caption-color');
+    expect(markup).toContain('--pb-body-color');
+    expect(markup).toContain('--pb-caption-size');
+  });
+
+  it('keeps alt and caption separate', () => {
+    // alt is the accessible description, caption is visible prose; the two are
+    // rarely the same sentence, so neither may stand in for the other.
+    const markup = html({ alt: 'A map of the world', caption: 'Figure 1' });
+    expect(markup).toContain('alt="A map of the world"');
+    expect(markup).toContain('>Figure 1</figcaption>');
+  });
+
+  it('renders the caption as light markdown, like every other copy field', () => {
+    // Table, Carousel and CallToAction captions all go through renderRichText,
+    // so `**bold**` cannot mean one thing in one caption and another here.
+    expect(html({ caption: '**Figure 1** — the map' })).toContain('<strong');
+  });
+
+  it('escapes caption text rather than emitting it as markup', () => {
+    expect(html({ caption: '<b>bold</b>' })).not.toContain('<b>bold</b>');
+  });
+
+  it('emits a bare <img> when no caption is set', () => {
+    // Existing pages carry no caption prop at all — `undefined`, not `''`, is
+    // what Puck hands the block for them — and must render exactly as they did
+    // before the field existed.
+    const markup = html({ caption: undefined });
+    expect(markup).not.toContain('figure');
+    expect(markup.startsWith('<img')).toBe(true);
+    expect(markup).toContain('class="my-3"');
+  });
+
+  it('treats an empty or blank caption as no caption', () => {
+    // Whitespace-only would otherwise be truthy and render an empty caption
+    // box under the image.
+    const bare = html({ caption: undefined });
+    expect(html({ caption: '' })).toBe(bare);
+    expect(html({ caption: '   ' })).toBe(bare);
+  });
+
+  it('leaves the empty-src placeholder alone', () => {
+    const markup = html({ src: '', caption: 'A caption' });
+    expect(markup).toContain('No image selected');
+    expect(markup).not.toContain('figcaption');
+  });
+
+  it('still hides a decorative image from screen readers', () => {
+    const markup = html({ altKind: 'decorative', caption: 'A caption' });
+    expect(markup).toContain('alt=""');
+    expect(markup).toContain('aria-hidden="true"');
+    expect(markup).toContain('<figcaption');
+  });
+});

{simple_module_pagebuilder-0.0.2 → simple_module_pagebuilder-0.0.3}/pagebuilder/components/blocks/Image.tsx

@@ -6,6 +6,7 @@ import {
   lookupAsset,
   type MediaAssetRead,
 } from '../../utils/api';
+import { renderRichText } from '../widgets/_internal/rich-text';
 import { MediaPicker } from './MediaPicker';
 
 type AltKind = 'meaningful' | 'decorative';
@@ -14,6 +15,10 @@ interface ImageProps {
   src: string;
   alt: string;
   altKind: AltKind;
+  /** Visible prose under the image, as light markdown. Distinct from `alt`,
+   *  which describes the image to a screen reader — the two are rarely the
+   *  same sentence. */
+  caption?: string;
   width: number | null;
   height: number | null;
   objectFit: 'cover' | 'contain' | 'fill';
@@ -21,6 +26,14 @@ interface ImageProps {
   sizes: string;
 }
 
+// Captions read their look from the design pack the way the widget set does,
+// so a tenant restyles them by overriding tokens instead of patching this
+// block. `--pb-caption-color` falls through to the pack's body colour, which
+// is what an unstyled pack (and widgets-base) already defines.
+const CAPTION_CLASS =
+  'mt-2 text-[length:var(--pb-caption-size,0.875rem)] leading-[var(--pb-body-leading,1.625)]';
+const CAPTION_STYLE = { color: 'var(--pb-caption-color, var(--pb-body-color))' };
+
 function resolveSizes(srcset: string, sizes: string): string | undefined {
   if (sizes) return sizes;
   // Browsers assume 100vw when sizes is omitted but srcset is present;
@@ -50,6 +63,7 @@ export const ImageBlock: ComponentConfig<ImageProps> = {
       ],
     },
     alt: { type: 'text' },
+    caption: { type: 'text', label: 'Caption' },
     width: { type: 'number' },
     height: { type: 'number' },
     objectFit: {
@@ -67,6 +81,7 @@ export const ImageBlock: ComponentConfig<ImageProps> = {
     src: '',
     alt: '',
     altKind: 'meaningful',
+    caption: '',
     width: null,
     height: null,
     objectFit: 'cover',
@@ -96,7 +111,7 @@ export const ImageBlock: ComponentConfig<ImageProps> = {
       },
     };
   },
-  render: ({ src, alt, altKind, width, height, objectFit, srcset, sizes }) => {
+  render: ({ src, alt, altKind, caption, width, height, objectFit, srcset, sizes }) => {
     if (!src) {
       return (
         <div className="my-3 p-6 border-2 border-dashed border-gray-300 rounded text-center text-gray-500 text-sm">
@@ -105,7 +120,11 @@ export const ImageBlock: ComponentConfig<ImageProps> = {
       );
     }
     const decorative = altKind === 'decorative';
-    return (
+    // Trimmed, so a caption of nothing but spaces is no caption: it would
+    // otherwise render an empty <figcaption> box under the image. Same rule
+    // the translation extractor applies to every other copy field.
+    const hasCaption = Boolean(caption?.trim());
+    const image = (
       <img
         src={src}
         srcSet={srcset || undefined}
@@ -118,8 +137,23 @@ export const ImageBlock: ComponentConfig<ImageProps> = {
         loading="lazy"
         decoding="async"
         style={{ objectFit, maxWidth: '100%' }}
-        className="my-3"
+        // Inside a <figure> the margin belongs to the figure, and `block`
+        // drops the inline descender gap above the caption. Uncaptioned
+        // images keep the exact markup they had before the field existed.
+        className={hasCaption ? 'block' : 'my-3'}
       />
     );
+    if (!hasCaption) return image;
+    return (
+      <figure className="my-3">
+        {image}
+        <figcaption className={CAPTION_CLASS} style={CAPTION_STYLE}>
+          {/* Light markdown, like every other copy field in the module — the
+              Table/Carousel/CallToAction captions all render this way, so
+              `**Figure 1**` can't work in one caption and not another. */}
+          {renderRichText(caption)}
+        </figcaption>
+      </figure>
+    );
   },
 };

{simple_module_pagebuilder-0.0.2 → simple_module_pagebuilder-0.0.3}/pagebuilder/conversion/blocks-to-html.test.ts

@@ -58,6 +58,30 @@ describe('blocksToHtml', () => {
     ).toBe('<img src="/a.png" alt="" width="800" height="600">');
   });
 
+  it('carries an image caption across as a figure, so it is not lost silently', () => {
+    // The caption is authored copy. Emitting the bare <img> would drop it with
+    // no `lossyTypes` entry to warn the caller, because the block itself
+    // converts fine — the quiet loss this module exists to avoid.
+    expect(
+      blocksToHtml([b('Image', { src: '/a.png', alt: 'A map', caption: 'Figure 1' })]).html,
+    ).toBe('<figure><img src="/a.png" alt="A map"><figcaption>Figure 1</figcaption></figure>');
+    // Inline markdown, matching what the block renders, escaped as it goes.
+    expect(
+      blocksToHtml([b('Image', { src: '/a.png', alt: '', caption: '**Fig 1** <b>' })]).html,
+    ).toBe(
+      '<figure><img src="/a.png" alt=""><figcaption><strong>Fig 1</strong> &lt;b&gt;</figcaption></figure>',
+    );
+  });
+
+  it('emits a bare img for a missing or blank caption', () => {
+    expect(blocksToHtml([b('Image', { src: '/a.png', alt: '' })]).html).toBe(
+      '<img src="/a.png" alt="">',
+    );
+    expect(blocksToHtml([b('Image', { src: '/a.png', alt: '', caption: '   ' })]).html).toBe(
+      '<img src="/a.png" alt="">',
+    );
+  });
+
   it('treats Html as lossy unless raw markup is explicitly asked for', () => {
     // The Html widget renders its markup inside `<iframe sandbox>` because a
     // ContentEditor's input isn't fully trusted. This function's output has no

{simple_module_pagebuilder-0.0.2 → simple_module_pagebuilder-0.0.3}/pagebuilder/conversion/blocks-to-html.ts

@@ -8,7 +8,7 @@
  * then say exactly what didn't come across.
  */
 
-import { escapeHtml, markdownToHtml } from '../utils/markdown';
+import { escapeHtml, inlineMarkdownToHtml, markdownToHtml } from '../utils/markdown';
 import type { PuckBlock } from './types';
 
 export type BlocksToHtmlResult = { html: string; lossyTypes: string[] };
@@ -83,7 +83,15 @@ function blockToHtml(block: PuckBlock, options: BlocksToHtmlOptions): string | n
       const dims = ['width', 'height']
         .map((key) => (typeof props[key] === 'number' ? ` ${key}="${props[key]}"` : ''))
         .join('');
-      return `<img src="${escapeHtml(props.src)}" alt="${escapeHtml(alt)}"${dims}>`;
+      const img = `<img src="${escapeHtml(props.src)}" alt="${escapeHtml(alt)}"${dims}>`;
+      // The caption is authored copy, not a rendering detail — dropping it
+      // here would lose it silently, and `lossyTypes` couldn't name it either
+      // because the rest of the block converts fine. Same `<figure>` shape the
+      // block renders, so an export reads the way the page does. Inline
+      // markdown, as the block treats it; the converter escapes as it goes.
+      const caption = typeof props.caption === 'string' ? props.caption.trim() : '';
+      if (!caption) return img;
+      return `<figure>${img}<figcaption>${inlineMarkdownToHtml(caption)}</figcaption></figure>`;
     }
 
     case 'Quote': {

{simple_module_pagebuilder-0.0.2 → simple_module_pagebuilder-0.0.3}/pagebuilder/static/widgets-base.css

@@ -36,6 +36,13 @@
 	   EYEBROW_CASE_STYLE's fallbacks in _shared/mask.ts, so removing them
 	   changes nothing for the sentence-case eyebrows and lets each call site
 	   state its own prior literal. Tenants still override via their design pack. */
+	/* Image-block captions. Deliberately NOT defaulted here, for the same
+	   reason as the eyebrow tokens above: `--pb-caption-color` is read as
+	   `var(--pb-caption-color, var(--pb-body-color))` and `--pb-caption-size`
+	   as `var(--pb-caption-size, 0.875rem)`, and declaring either globally
+	   would make the call site's own fallback unreachable. Listed here so a
+	   pack author can find them — set them in the design pack to restyle
+	   captions without touching the block. */
 	/* Hero geometry (consumed by the Hero/PageHeader widgets). */
 	--pb-hero-min-h: 560px;
 	--pb-hero-logo-max-h: 14rem;

{simple_module_pagebuilder-0.0.2 → simple_module_pagebuilder-0.0.3}/pagebuilder/utils/markdown.ts

@@ -134,7 +134,14 @@ export function parseInlineTokens(text: string): InlineToken[] {
   return tokens;
 }
 
-function inlineMarkdownToHtml(text: string): string {
+/**
+ * One line of inline markdown → HTML, with no block wrapper.
+ *
+ * Exported for the places that need the emphasis but must not gain a `<p>`:
+ * an image's `<figcaption>` is phrasing content the block renders inline, so
+ * `markdownToHtml` would wrap it in a paragraph the page never had.
+ */
+export function inlineMarkdownToHtml(text: string): string {
   return parseInlineTokens(text)
     .map((token) => {
       const escaped = escapeHtml(token.content);

{simple_module_pagebuilder-0.0.2 → simple_module_pagebuilder-0.0.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_pagebuilder"
-version = "0.0.2"
+version = "0.0.3"
 description = "Drag-and-drop visual page builder for simple_module apps"
 readme = "README.md"
 license = "MIT"