simple-module-pagebuilder 0.0.1__py3-none-any.whl

pagebuilder/components/DiffSummary.tsx

@@ -0,0 +1,107 @@
+import type React from 'react';
+import type { RevisionDiff } from '../utils/api';
+
+interface Props {
+  diff: RevisionDiff;
+}
+
+function renderValue(value: unknown): string {
+  if (value === null || value === undefined) return '∅';
+  if (typeof value === 'string') return value || '""';
+  return JSON.stringify(value);
+}
+
+/**
+ * Compact, scannable diff: metadata table (only changed fields) plus
+ * three lists of blocks (added / removed / changed). Designed to fit
+ * inside the editor's history panel without a separate page.
+ */
+export function DiffSummary({ diff }: Props): React.JSX.Element {
+  const { metadata, blocks } = diff;
+  const metaKeys = Object.keys(metadata);
+  const totalChanges =
+    metaKeys.length + blocks.added.length + blocks.removed.length + blocks.changed.length;
+
+  if (totalChanges === 0) {
+    return (
+      <div
+        className="mt-3 rounded border border-gray-200 bg-white p-3 text-xs text-gray-500"
+        data-testid="diff-summary"
+      >
+        No changes between these revisions.
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className="mt-3 rounded border border-gray-200 bg-white p-3 text-xs space-y-2"
+      data-testid="diff-summary"
+    >
+      {metaKeys.length > 0 && (
+        <div>
+          <div className="font-semibold text-gray-700">Metadata</div>
+          <ul className="ml-3 list-disc">
+            {metaKeys.map((key) => (
+              <li key={key}>
+                <span className="font-mono">{key}</span>:{' '}
+                <span className="text-red-600 line-through">
+                  {renderValue(metadata[key].before)}
+                </span>{' '}
+                → <span className="text-green-700">{renderValue(metadata[key].after)}</span>
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+      {blocks.added.length > 0 && (
+        <div>
+          <div className="font-semibold text-green-700">Added ({blocks.added.length})</div>
+          <ul className="ml-3 list-disc">
+            {blocks.added.map((b) => (
+              <li key={b.id}>
+                <span className="font-mono">{b.type ?? '?'}</span>{' '}
+                <span className="text-gray-500">({b.id})</span>
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+      {blocks.removed.length > 0 && (
+        <div>
+          <div className="font-semibold text-red-700">Removed ({blocks.removed.length})</div>
+          <ul className="ml-3 list-disc">
+            {blocks.removed.map((b) => (
+              <li key={b.id}>
+                <span className="font-mono">{b.type ?? '?'}</span>{' '}
+                <span className="text-gray-500">({b.id})</span>
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+      {blocks.changed.length > 0 && (
+        <div>
+          <div className="font-semibold text-amber-700">Changed ({blocks.changed.length})</div>
+          <ul className="ml-3 list-disc">
+            {blocks.changed.map((b) => (
+              <li key={b.id}>
+                <span className="font-mono">{b.type ?? '?'}</span>{' '}
+                <span className="text-gray-500">({b.id})</span>
+                {b.type_before && (
+                  <span className="text-gray-500">
+                    {' '}
+                    — was <span className="font-mono">{b.type_before}</span>
+                  </span>
+                )}
+                {b.fields.length > 0 && (
+                  <span className="text-gray-700">: {b.fields.join(', ')}</span>
+                )}
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+    </div>
+  );
+}

pagebuilder/components/ScheduledBadge.tsx

@@ -0,0 +1,34 @@
+import type { PageStatus } from '../utils/api';
+
+interface Props {
+  status: PageStatus;
+  publishAt: string | null;
+  unpublishAt: string | null;
+}
+
+/**
+ * Inline pill rendered next to ``StatusBadge`` when a page has a
+ * pending scheduler-driven flip. Drafts surface the upcoming publish
+ * time; published pages surface the upcoming unpublish time. Pages
+ * with no schedule for their current state render nothing — so callers
+ * can drop this in unconditionally.
+ */
+export function ScheduledBadge({ status, publishAt, unpublishAt }: Props) {
+  const target =
+    status === 'draft' && publishAt
+      ? { kind: 'publish' as const, at: publishAt }
+      : status === 'published' && unpublishAt
+        ? { kind: 'unpublish' as const, at: unpublishAt }
+        : null;
+  if (!target) return null;
+  const label = target.kind === 'publish' ? 'Scheduled to publish' : 'Scheduled to unpublish';
+  return (
+    <span
+      className="ml-2 inline-block text-xs font-medium px-2 py-1 rounded bg-blue-100 text-blue-800"
+      title={new Date(target.at).toLocaleString()}
+      data-testid="scheduled-badge"
+    >
+      {label} {new Date(target.at).toLocaleString()}
+    </span>
+  );
+}

pagebuilder/components/StatusBadge.tsx

@@ -0,0 +1,21 @@
+import { Badge } from '@simple-module-py/ui/components/ui/badge';
+
+import type { PageStatus } from '../utils/api';
+
+// The e2e suite asserts on this text verbatim — getByText('published',
+// { exact: true }) — so these labels stay lowercase and unabbreviated.
+const LABELS: Record<PageStatus, string> = {
+  published: 'published',
+  submitted_for_review: 'pending review',
+  draft: 'draft',
+};
+
+const VARIANTS: Record<PageStatus, 'default' | 'secondary' | 'outline'> = {
+  published: 'default',
+  submitted_for_review: 'secondary',
+  draft: 'outline',
+};
+
+export function StatusBadge({ status }: { status: PageStatus }) {
+  return <Badge variant={VARIANTS[status]}>{LABELS[status]}</Badge>;
+}

pagebuilder/components/blockRegistry.test.ts

@@ -0,0 +1,56 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+
+import {
+  type AnyBlock,
+  declareBuiltInBlocks,
+  registeredBlocks,
+  registerPuckBlocks,
+  registryVersion,
+  resetBlockRegistry,
+} from './blockRegistry';
+
+const stub = { render: () => null } as unknown as AnyBlock;
+
+describe('block registry', () => {
+  beforeEach(() => {
+    declareBuiltInBlocks(['Heading', 'Text']);
+    resetBlockRegistry();
+  });
+
+  it('collects a registration', () => {
+    registerPuckBlocks({ blocks: { Widget: stub } });
+    expect(registeredBlocks().flatMap((r) => Object.keys(r.blocks))).toContain('Widget');
+  });
+
+  it('bumps the version on each registration', () => {
+    const before = registryVersion();
+    registerPuckBlocks({ blocks: { Widget: stub } });
+    expect(registryVersion()).toBeGreaterThan(before);
+  });
+
+  it('refuses to shadow a block pagebuilder already ships', () => {
+    // Block names are the `type` stored in page content, so a duplicate would
+    // make two blocks each render the other's saved data.
+    expect(() => registerPuckBlocks({ blocks: { Heading: stub } })).toThrow(/Heading/);
+  });
+
+  it('refuses to register the same name twice', () => {
+    registerPuckBlocks({ blocks: { Widget: stub } });
+    expect(() => registerPuckBlocks({ blocks: { Widget: stub } })).toThrow(/Widget/);
+  });
+
+  it('keeps the built-ins reserved across a reset', () => {
+    resetBlockRegistry();
+    expect(() => registerPuckBlocks({ blocks: { Text: stub } })).toThrow(/Text/);
+  });
+
+  it('carries the category through', () => {
+    registerPuckBlocks({ blocks: { Widget: stub }, category: { key: 'feeds', title: 'Feeds' } });
+    expect(registeredBlocks()[0].category).toEqual({ key: 'feeds', title: 'Feeds' });
+  });
+
+  it('defaults to page-only, not layout', () => {
+    registerPuckBlocks({ blocks: { Widget: stub } });
+    expect(registeredBlocks()[0].layout).toBeUndefined();
+  });
+});

pagebuilder/components/blockRegistry.ts

@@ -0,0 +1,80 @@
+/**
+ * Lets another module contribute Puck blocks without pagebuilder importing it.
+ *
+ * The framework's registries — menu, permissions, public routes, design packs —
+ * are all backend. This is the frontend equivalent, and the reason it exists is
+ * dependency direction: the news module knows about pagebuilder, so pagebuilder
+ * must not know about news.
+ *
+ * Registration is a side effect of importing a module's `puck-blocks.ts`. The
+ * host imports them all eagerly at app start (see `host/client_app/blocks.ts`),
+ * which is what guarantees the registry is populated before the first render.
+ */
+
+import type { ComponentConfig } from '@puckeditor/core';
+
+// Puck's ComponentConfig is invariant in its props, so a registry that holds
+// configs for unrelated prop shapes cannot be typed precisely. The runtime
+// shape is what matters here; each module keeps its own widget types honest.
+// biome-ignore lint/suspicious/noExplicitAny: a heterogeneous registry has no single prop type
+export type AnyBlock = ComponentConfig<any>;
+
+export interface BlockRegistration {
+  /** Block name → config. The name is the `type` stored in page content. */
+  blocks: Record<string, AnyBlock>;
+  /** Palette group. Blocks with no category land in Puck's "Other". */
+  category?: { key: string; title: string };
+  /** Also offer these in the site-layout palette. Default false. */
+  layout?: boolean;
+}
+
+let registrations: BlockRegistration[] = [];
+let takenNames = new Set<string>();
+let builtIns: readonly string[] = [];
+let version = 0;
+
+/**
+ * Declare the names pagebuilder itself ships, so a module cannot shadow one.
+ *
+ * Called once by puckConfig at import time rather than hardcoded here, which
+ * would be a second list to keep in sync.
+ */
+export function declareBuiltInBlocks(names: readonly string[]): void {
+  builtIns = names;
+  for (const name of names) takenNames.add(name);
+}
+
+export function registerPuckBlocks(registration: BlockRegistration): void {
+  for (const name of Object.keys(registration.blocks)) {
+    if (takenNames.has(name)) {
+      throw new Error(
+        `Puck block "${name}" is already registered. Block names are the \`type\` ` +
+          'stored in page content, so two blocks sharing one would each render ' +
+          "the other's saved data.",
+      );
+    }
+    takenNames.add(name);
+  }
+  registrations = [...registrations, registration];
+  version += 1;
+}
+
+export function registeredBlocks(): readonly BlockRegistration[] {
+  return registrations;
+}
+
+/**
+ * Bumped on every registration. The config builders memoise on this rather
+ * than caching unconditionally, so a registration that lands after the first
+ * read is not silently dropped.
+ */
+export function registryVersion(): number {
+  return version;
+}
+
+/** Test-only: drop every registration, keeping the declared built-ins. */
+export function resetBlockRegistry(): void {
+  registrations = [];
+  takenNames = new Set(builtIns);
+  version += 1;
+}

pagebuilder/components/blocks/Button.tsx

@@ -0,0 +1,142 @@
+import type { ComponentConfig } from '@puckeditor/core';
+import type { CSSProperties } from 'react';
+
+import { cn } from '../../utils/widgetUtils';
+import { renderRichText } from '../widgets/_internal/rich-text';
+
+interface ButtonProps {
+  label: string;
+  href: string;
+  variant: 'primary' | 'secondary' | 'outline' | 'ghost';
+  size: 'sm' | 'md' | 'lg';
+  target: '_self' | '_blank';
+  /**
+   * Optional CSS colour override. "primary" uses it as the background (with
+   * `--pb-surface-contrast` text); the other variants use it as the text and
+   * border colour. Blank keeps the variant's own palette.
+   */
+  color: string;
+  /**
+   * Left placement on the 12-column page grid. "none" keeps the button at the
+   * container's left edge; "4" starts it at the 4th column so it lines up with
+   * an indented text column (the Markdown widget's `indent`).
+   */
+  indent: 'none' | '4';
+}
+
+// `primary`/`ghost` read the branding ramp rather than a fixed blue, so the
+// button follows Settings → Branding like the rest of the widget set. The
+// previous `bg-blue-600` ignored it.
+const variantClass: Record<ButtonProps['variant'], string> = {
+  primary: 'bg-primary-700 hover:bg-primary-800 text-white',
+  secondary: 'bg-gray-700 hover:bg-gray-800 text-white',
+  outline:
+    'border border-gray-300 text-gray-900 hover:bg-gray-50 dark:text-white dark:border-gray-700 dark:hover:bg-gray-800',
+  ghost:
+    'text-[color:var(--pb-button-ghost-fg,var(--color-primary-700))] hover:bg-[var(--pb-button-ghost-bg-hover,var(--color-primary-50))]',
+};
+
+const sizeClass: Record<ButtonProps['size'], string> = {
+  sm: 'py-1.5 px-3 text-sm',
+  md: 'py-2 px-5 text-base',
+  lg: 'py-3 px-7 text-lg',
+};
+
+export const ButtonBlock: ComponentConfig<ButtonProps> = {
+  label: 'Button',
+  fields: {
+    label: { type: 'text', label: 'Label' },
+    href: { type: 'text', label: 'Link' },
+    variant: {
+      type: 'select',
+      label: 'Variant',
+      options: [
+        { label: 'Primary', value: 'primary' },
+        { label: 'Secondary', value: 'secondary' },
+        { label: 'Outline', value: 'outline' },
+        { label: 'Ghost', value: 'ghost' },
+      ],
+    },
+    size: {
+      type: 'select',
+      label: 'Size',
+      options: [
+        { label: 'Small', value: 'sm' },
+        { label: 'Medium', value: 'md' },
+        { label: 'Large', value: 'lg' },
+      ],
+    },
+    target: {
+      type: 'radio',
+      label: 'Link target',
+      options: [
+        { label: 'Same tab', value: '_self' },
+        { label: 'New tab', value: '_blank' },
+      ],
+    },
+    color: { type: 'text', label: 'Colour (CSS, optional)' },
+    indent: {
+      type: 'select',
+      label: 'Grid indent',
+      options: [
+        { label: 'None', value: 'none' },
+        { label: '4th column', value: '4' },
+      ],
+    },
+  },
+  defaultProps: {
+    label: 'Click me',
+    href: '#',
+    variant: 'primary',
+    size: 'md',
+    target: '_self',
+    color: '',
+    indent: 'none',
+  },
+  // `size`, `color` and `indent` are defaulted again in the signature, not
+  // only in `defaultProps`. Those apply to a block the author drops *now* —
+  // every Button already stored on a page predates these fields and arrives
+  // with them undefined, which would index the class maps to `undefined` and
+  // put that literal into the class list.
+  render: ({ label, href, variant, size = 'md', target, color = '', indent = 'none' }) => {
+    // Pill radius is theme-driven; the fallback is the previous `rounded`.
+    const style: CSSProperties = { borderRadius: 'var(--pb-button-radius, 0.375rem)' };
+    if (color) {
+      if (variant === 'primary') {
+        style.backgroundColor = color;
+        style.color = 'var(--pb-surface-contrast, #ffffff)';
+      } else {
+        style.color = color;
+        style.borderColor = color;
+      }
+    }
+    return (
+      <div className={cn(indent === '4' && 'lg:grid lg:grid-cols-12 lg:gap-6')}>
+        <a
+          href={href}
+          target={target}
+          rel={target === '_blank' ? 'noopener noreferrer' : undefined}
+          className={cn(
+            'inline-flex items-center justify-center font-medium transition-colors',
+            indent === '4' && 'lg:col-start-4 lg:col-span-9 lg:justify-self-start',
+            variantClass[variant],
+            sizeClass[size],
+          )}
+          style={style}
+        >
+          {/* Links off: this is already inside an `<a>`, and nesting anchors
+              is invalid HTML. */}
+          {renderRichText(label || '', { allowLinks: false })}
+          {/* Trailing arrow, off by default (`--pb-button-arrow-display`) and
+              suppressed when the label carries its own — a "← Back" link
+              should not come out as "← Back →". */}
+          {!/[←→]/.test(label ?? '') && (
+            <span aria-hidden="true" className="ml-2 [display:var(--pb-button-arrow-display,none)]">
+              →
+            </span>
+          )}
+        </a>
+      </div>
+    );
+  },
+};

pagebuilder/components/blocks/Columns.tsx

@@ -0,0 +1,64 @@
+import type { ComponentConfig, Slot } from '@puckeditor/core';
+
+export interface ColumnsProps {
+  /**
+   * `width` is a flex ratio, not a fraction — two columns at 1 and 2 split
+   * 1/3 : 2/3. `content` is the column's own slot; it lives inside the array
+   * so the number of columns stays author-controlled. A top-level slot field
+   * per column would cap the block at however many we declared.
+   */
+  columns: { width: number; content: Slot }[];
+  gap: 'sm' | 'md' | 'lg';
+}
+
+const gapClass: Record<ColumnsProps['gap'], string> = {
+  sm: 'gap-2',
+  md: 'gap-4',
+  lg: 'gap-8',
+};
+
+export const ColumnsBlock: ComponentConfig<ColumnsProps> = {
+  label: 'Columns',
+  fields: {
+    columns: {
+      type: 'array',
+      arrayFields: {
+        width: { type: 'number' },
+        content: { type: 'slot' },
+      },
+      defaultItemProps: { width: 1, content: [] },
+    },
+    gap: {
+      type: 'select',
+      options: [
+        { label: 'Small', value: 'sm' },
+        { label: 'Medium', value: 'md' },
+        { label: 'Large', value: 'lg' },
+      ],
+    },
+  },
+  defaultProps: {
+    columns: [
+      { width: 1, content: [] },
+      { width: 1, content: [] },
+    ],
+    gap: 'md',
+  },
+  render: ({ columns, gap }) => (
+    <div className={`flex flex-wrap ${gapClass[gap]} my-4`}>
+      {columns.map((col, idx) => {
+        // Puck hands each slot back as a component, so it has to be bound to a
+        // capitalised name before it can be used as an element.
+        const Content = col.content;
+        return (
+          // The index IS the column's identity — it's what the pre-slots zone
+          // name was derived from, and what the migration maps back onto.
+          // biome-ignore lint/suspicious/noArrayIndexKey: index is the column's identity
+          <div key={idx} style={{ flex: col.width }} className="min-w-0">
+            <Content />
+          </div>
+        );
+      })}
+    </div>
+  ),
+};

pagebuilder/components/blocks/Heading.tsx

@@ -0,0 +1,92 @@
+import type { ComponentConfig } from '@puckeditor/core';
+import type { CSSProperties } from 'react';
+
+import { cn } from '../../utils/widgetUtils';
+import { renderRichText } from '../widgets/_internal/rich-text';
+
+interface HeadingProps {
+  text: string;
+  /**
+   * Stored as `h1`…`h6` rather than upstream's `1`…`6`. The enum is an
+   * internal representation, not something an author ever sees, and every
+   * Heading already on a page uses this spelling — adopting the other one
+   * would mean migrating all of them to change nothing visible.
+   */
+  level: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+  align: 'left' | 'center' | 'right';
+}
+
+// A lookup map rather than `text-${align}`: Tailwind's scanner only emits
+// classes it can see spelled out, and an interpolated name is invisible to it.
+// The old form worked by accident — these three names happen to appear
+// literally in other files, and would have silently stopped working the day
+// they didn't.
+const alignClass: Record<HeadingProps['align'], string> = {
+  left: 'text-left',
+  center: 'text-center',
+  right: 'text-right',
+};
+
+// Sizes only. Weight, tracking and face for display headings come from the
+// design-pack tokens, so one block renders in each pack's style — the previous
+// hardcoded `font-bold` overrode the pack.
+const sizeClass: Record<HeadingProps['level'], string> = {
+  h1: 'text-4xl sm:text-5xl lg:text-6xl leading-[1.1]',
+  h2: 'text-3xl sm:text-4xl lg:text-5xl leading-[1.1]',
+  h3: 'text-2xl sm:text-3xl',
+  h4: 'text-xl sm:text-2xl font-medium',
+  h5: 'text-lg sm:text-xl font-medium',
+  h6: 'text-base sm:text-lg font-medium',
+};
+
+/** h1–h3 are display headings and take the pack's display face and weight. */
+const DISPLAY_LEVELS = new Set<HeadingProps['level']>(['h1', 'h2', 'h3']);
+
+function headingStyle(level: HeadingProps['level']): CSSProperties {
+  const style: CSSProperties = { color: 'var(--pb-heading-color)' };
+  if (DISPLAY_LEVELS.has(level)) {
+    style.fontWeight = 'var(--pb-display-weight)' as CSSProperties['fontWeight'];
+    style.letterSpacing = 'var(--pb-display-tracking)';
+    style.fontFamily = 'var(--pb-display-font)';
+  }
+  return style;
+}
+
+export const HeadingBlock: ComponentConfig<HeadingProps> = {
+  label: 'Heading',
+  fields: {
+    text: { type: 'text', label: 'Text' },
+    level: {
+      type: 'select',
+      label: 'Level',
+      options: [
+        { label: 'H1', value: 'h1' },
+        { label: 'H2', value: 'h2' },
+        { label: 'H3', value: 'h3' },
+        { label: 'H4', value: 'h4' },
+        { label: 'H5', value: 'h5' },
+        { label: 'H6', value: 'h6' },
+      ],
+    },
+    align: {
+      type: 'radio',
+      label: 'Alignment',
+      options: [
+        { label: 'Left', value: 'left' },
+        { label: 'Center', value: 'center' },
+        { label: 'Right', value: 'right' },
+      ],
+    },
+  },
+  defaultProps: { text: 'Heading', level: 'h2', align: 'left' },
+  render: ({ text, level = 'h2', align = 'left' }) => {
+    const Tag = level;
+    return (
+      <div className="container mx-auto px-4 py-2">
+        <Tag className={cn(sizeClass[level], alignClass[align])} style={headingStyle(level)}>
+          {renderRichText(text)}
+        </Tag>
+      </div>
+    );
+  },
+};