superdoc-dev
diff --git a/‎packages/layout-engine/contracts/src/header-footer-inheritance.test.ts‎
Lines changed: 98 additions & 0 deletions b/‎packages/layout-engine/contracts/src/header-footer-inheritance.test.ts‎
Lines changed: 98 additions & 0 deletions
diff --git a/‎packages/layout-engine/contracts/src/header-footer-inheritance.ts‎
Lines changed: 66 additions & 0 deletions b/‎packages/layout-engine/contracts/src/header-footer-inheritance.ts‎
Lines changed: 66 additions & 0 deletions
diff --git a/‎packages/layout-engine/contracts/src/header-footer-resolution.test.ts‎
Lines changed: 132 additions & 0 deletions b/‎packages/layout-engine/contracts/src/header-footer-resolution.test.ts‎
Lines changed: 132 additions & 0 deletions
diff --git a/‎packages/layout-engine/contracts/src/header-footer-resolution.ts‎
Lines changed: 88 additions & 0 deletions b/‎packages/layout-engine/contracts/src/header-footer-resolution.ts‎
Lines changed: 88 additions & 0 deletions
@@ -0,0 +1,98 @@
+import { describe, expect, it } from 'vitest';
+import {
+  resolveInheritedHeaderFooterRef,
+  resolveInheritedHeaderFooterRefWithType,
+} from './header-footer-inheritance.js';
+
+describe('header/footer inheritance', () => {
+  it('uses legacy refs when section maps are empty', () => {
+    const ref = resolveInheritedHeaderFooterRef({
+      identifier: {
+        headerIds: { default: 'legacy-default' },
+        sectionHeaderIds: new Map(),
+      },
+      sectionIndex: 0,
+      kind: 'header',
+      variantType: 'default',
+    });
+
+    expect(ref).toBe('legacy-default');
+  });
+
+  it('returns null for section zero when no page, section, or legacy refs exist', () => {
+    const ref = resolveInheritedHeaderFooterRef({
+      identifier: { sectionHeaderIds: new Map() },
+      sectionIndex: 0,
+      kind: 'header',
+      variantType: 'default',
+    });
+
+    expect(ref).toBeNull();
+  });
+
+  it('walks back past intermediate sections with no entry', () => {
+    const ref = resolveInheritedHeaderFooterRef({
+      identifier: {
+        sectionHeaderIds: new Map([[0, { first: 'section-0-first' }]]),
+      },
+      sectionIndex: 3,
+      kind: 'header',
+      variantType: 'first',
+    });
+
+    expect(ref).toBe('section-0-first');
+  });
+
+  it('prefers page refs over section refs', () => {
+    const resolved = resolveInheritedHeaderFooterRefWithType({
+      identifier: {
+        sectionFooterIds: new Map([[0, { default: 'section-default' }]]),
+      },
+      sectionIndex: 0,
+      kind: 'footer',
+      variantType: 'default',
+      pageRefs: { default: 'page-default' },
+    });
+
+    expect(resolved).toEqual({ ref: 'page-default', variantType: 'default' });
+  });
+
+  it('uses default refs for odd pages and reports the effective variant', () => {
+    const resolved = resolveInheritedHeaderFooterRefWithType({
+      identifier: {
+        headerIds: { default: 'legacy-default' },
+      },
+      sectionIndex: 0,
+      kind: 'header',
+      variantType: 'odd',
+    });
+
+    expect(resolved).toEqual({ ref: 'legacy-default', variantType: 'default' });
+  });
+
+  it('does not fall back from first to default', () => {
+    const ref = resolveInheritedHeaderFooterRef({
+      identifier: {
+        headerIds: { default: 'legacy-default' },
+      },
+      sectionIndex: 0,
+      kind: 'header',
+      variantType: 'first',
+    });
+
+    expect(ref).toBeNull();
+  });
+
+  it('does not fall back from even to default', () => {
+    const ref = resolveInheritedHeaderFooterRef({
+      identifier: {
+        headerIds: { default: 'legacy-default' },
+      },
+      sectionIndex: 0,
+      kind: 'header',
+      variantType: 'even',
+    });
+
+    expect(ref).toBeNull();
+  });
+});
@@ -0,0 +1,66 @@
+import type { HeaderFooterType } from './index.js';
+
+export type HeaderFooterRefMap = Partial<Record<HeaderFooterType, string | null | undefined>>;
+
+export type HeaderFooterRefIdentifier = {
+  headerIds?: HeaderFooterRefMap;
+  footerIds?: HeaderFooterRefMap;
+  sectionCount?: number;
+  sectionHeaderIds?: Map<number, HeaderFooterRefMap>;
+  sectionFooterIds?: Map<number, HeaderFooterRefMap>;
+};
+
+export type ResolveInheritedHeaderFooterRefInput = {
+  identifier: HeaderFooterRefIdentifier;
+  sectionIndex: number;
+  kind: 'header' | 'footer';
+  variantType: HeaderFooterType;
+  pageRefs?: HeaderFooterRefMap;
+};
+
+export type ResolvedInheritedHeaderFooterRef = {
+  ref: string;
+  variantType: HeaderFooterType;
+};
+
+function resolveVariantRef(
+  refs: HeaderFooterRefMap | undefined,
+  variantType: HeaderFooterType,
+): ResolvedInheritedHeaderFooterRef | null {
+  if (!refs) return null;
+  const direct = refs[variantType];
+  if (direct) return { ref: direct, variantType };
+  if (variantType === 'odd' && refs.default) return { ref: refs.default, variantType: 'default' };
+  return null;
+}
+
+export function resolveInheritedHeaderFooterRefWithType({
+  identifier,
+  sectionIndex,
+  kind,
+  variantType,
+  pageRefs,
+}: ResolveInheritedHeaderFooterRefInput): ResolvedInheritedHeaderFooterRef | null {
+  const fromPage = resolveVariantRef(pageRefs, variantType);
+  if (fromPage) return fromPage;
+
+  const sectionMap = kind === 'header' ? identifier.sectionHeaderIds : identifier.sectionFooterIds;
+  const legacyIds = kind === 'header' ? identifier.headerIds : identifier.footerIds;
+
+  const sectionIds = sectionMap?.get(sectionIndex);
+  const fromSection = resolveVariantRef(sectionIds, variantType);
+  if (fromSection) return fromSection;
+
+  if (sectionMap) {
+    for (let index = sectionIndex - 1; index >= 0; index -= 1) {
+      const inherited = resolveVariantRef(sectionMap.get(index), variantType);
+      if (inherited) return inherited;
+    }
+  }
+
+  return resolveVariantRef(legacyIds, variantType);
+}
+
+export function resolveInheritedHeaderFooterRef(input: ResolveInheritedHeaderFooterRefInput): string | null {
+  return resolveInheritedHeaderFooterRefWithType(input)?.ref ?? null;
+}
@@ -0,0 +1,132 @@
+import { describe, expect, it } from 'vitest';
+import { resolveEffectiveHeaderFooterRef, selectHeaderFooterVariantForPage } from './header-footer-resolution.js';
+import type { HeaderFooterResolutionSection } from './header-footer-resolution.js';
+
+describe('header/footer effective ref resolution', () => {
+  it('inherits matching variants across more than one previous section', () => {
+    const sections: HeaderFooterResolutionSection[] = [
+      { sectionIndex: 0, titlePg: true, headerRefs: { first: 'h0-first' } },
+      { sectionIndex: 1, titlePg: true, headerRefs: { default: 'h1-default' } },
+      { sectionIndex: 2, titlePg: true, headerRefs: {} },
+    ];
+
+    expect(
+      resolveEffectiveHeaderFooterRef({ sections, sectionIndex: 2, kind: 'header', variant: 'first' }),
+    ).toMatchObject({
+      refId: 'h0-first',
+      matchedSectionIndex: 0,
+      matchedVariant: 'first',
+    });
+  });
+
+  it('preserves inherited missing variants when a later section partially overrides another variant', () => {
+    const sections: HeaderFooterResolutionSection[] = [
+      { sectionIndex: 0, footerRefs: { default: 'f0-default', even: 'f0-even' } },
+      { sectionIndex: 1, footerRefs: { default: 'f1-default' } },
+    ];
+
+    expect(
+      resolveEffectiveHeaderFooterRef({ sections, sectionIndex: 1, kind: 'footer', variant: 'even' }),
+    ).toMatchObject({
+      refId: 'f0-even',
+      matchedSectionIndex: 0,
+      matchedVariant: 'even',
+    });
+  });
+
+  it('does not let first inherit default when titlePg selects first', () => {
+    const sections: HeaderFooterResolutionSection[] = [
+      { sectionIndex: 0, titlePg: true, headerRefs: { default: 'h0-default' } },
+    ];
+
+    const variant = selectHeaderFooterVariantForPage({
+      documentPageNumber: 1,
+      sectionPageNumber: 1,
+      titlePg: true,
+      alternateHeaders: false,
+    });
+
+    expect(variant).toBe('first');
+    expect(resolveEffectiveHeaderFooterRef({ sections, sectionIndex: 0, kind: 'header', variant: 'first' })).toBeNull();
+  });
+
+  it('does not let even inherit default when odd/even headers are enabled', () => {
+    const sections: HeaderFooterResolutionSection[] = [{ sectionIndex: 0, headerRefs: { default: 'h0-default' } }];
+
+    expect(resolveEffectiveHeaderFooterRef({ sections, sectionIndex: 0, kind: 'header', variant: 'even' })).toBeNull();
+  });
+
+  it('resolves odd from explicit odd before OOXML default', () => {
+    const sections: HeaderFooterResolutionSection[] = [
+      { sectionIndex: 0, headerRefs: { default: 'h0-default' } },
+      { sectionIndex: 1, headerRefs: { odd: 'h1-odd', default: 'h1-default' } },
+    ];
+
+    expect(
+      resolveEffectiveHeaderFooterRef({ sections, sectionIndex: 1, kind: 'header', variant: 'odd' }),
+    ).toMatchObject({
+      refId: 'h1-odd',
+      matchedVariant: 'odd',
+    });
+  });
+
+  it('resolves odd from OOXML default when explicit odd is absent', () => {
+    const sections: HeaderFooterResolutionSection[] = [{ sectionIndex: 0, headerRefs: { default: 'h0-default' } }];
+
+    expect(
+      resolveEffectiveHeaderFooterRef({ sections, sectionIndex: 0, kind: 'header', variant: 'odd' }),
+    ).toMatchObject({
+      refId: 'h0-default',
+      matchedVariant: 'default',
+    });
+  });
+
+  it('uses document page number for even/odd selection', () => {
+    expect(
+      selectHeaderFooterVariantForPage({
+        documentPageNumber: 4,
+        sectionPageNumber: 1,
+        titlePg: false,
+        alternateHeaders: true,
+      }),
+    ).toBe('even');
+  });
+
+  it('accepts non-positive document page numbers for parity when the section page is valid', () => {
+    expect(
+      selectHeaderFooterVariantForPage({
+        documentPageNumber: 0,
+        sectionPageNumber: 1,
+        titlePg: false,
+        alternateHeaders: true,
+      }),
+    ).toBe('even');
+    expect(
+      selectHeaderFooterVariantForPage({
+        documentPageNumber: -1,
+        sectionPageNumber: 1,
+        titlePg: false,
+        alternateHeaders: true,
+      }),
+    ).toBe('odd');
+  });
+
+  it('returns null when the section page number is invalid', () => {
+    expect(
+      selectHeaderFooterVariantForPage({
+        documentPageNumber: 1,
+        sectionPageNumber: 0,
+        titlePg: false,
+        alternateHeaders: false,
+      }),
+    ).toBeNull();
+    expect(
+      selectHeaderFooterVariantForPage({
+        documentPageNumber: -1,
+        sectionPageNumber: -1,
+        titlePg: false,
+        alternateHeaders: true,
+      }),
+    ).toBeNull();
+  });
+});
@@ -0,0 +1,88 @@
+export type HeaderFooterKind = 'header' | 'footer';
+export type HeaderFooterVariant = 'default' | 'first' | 'even' | 'odd';
+
+export type HeaderFooterSectionRefs = Partial<Record<HeaderFooterVariant, string | null>>;
+
+export type HeaderFooterResolutionSection = {
+  sectionIndex: number;
+  titlePg?: boolean;
+  headerRefs?: HeaderFooterSectionRefs | null;
+  footerRefs?: HeaderFooterSectionRefs | null;
+};
+
+export type HeaderFooterVariantSelectionInput = {
+  documentPageNumber: number;
+  sectionPageNumber: number;
+  titlePg?: boolean;
+  alternateHeaders?: boolean;
+};
+
+export type HeaderFooterEffectiveRefInput = {
+  sections: readonly HeaderFooterResolutionSection[];
+  sectionIndex: number;
+  kind: HeaderFooterKind;
+  variant: HeaderFooterVariant;
+};
+
+export type HeaderFooterEffectiveRefResult = {
+  refId: string;
+  matchedSectionIndex: number;
+  matchedVariant: HeaderFooterVariant;
+};
+
+export function selectHeaderFooterVariantForPage({
+  documentPageNumber,
+  sectionPageNumber,
+  titlePg,
+  alternateHeaders,
+}: HeaderFooterVariantSelectionInput): HeaderFooterVariant | null {
+  if (!Number.isFinite(documentPageNumber) || !Number.isFinite(sectionPageNumber)) return null;
+  if (sectionPageNumber < 1) return null;
+  if (sectionPageNumber === 1 && titlePg === true) return 'first';
+  if (alternateHeaders === true) return documentPageNumber % 2 === 0 ? 'even' : 'odd';
+  return 'default';
+}
+
+function candidateVariantsFor(variant: HeaderFooterVariant): readonly HeaderFooterVariant[] {
+  return variant === 'odd' ? ['odd', 'default'] : [variant];
+}
+
+function sectionRefsFor(
+  section: HeaderFooterResolutionSection | undefined,
+  kind: HeaderFooterKind,
+): HeaderFooterSectionRefs | null | undefined {
+  return kind === 'header' ? section?.headerRefs : section?.footerRefs;
+}
+
+export function resolveEffectiveHeaderFooterRef({
+  sections,
+  sectionIndex,
+  kind,
+  variant,
+}: HeaderFooterEffectiveRefInput): HeaderFooterEffectiveRefResult | null {
+  if (sectionIndex < 0) return null;
+
+  const sectionsByIndex = new Map<number, HeaderFooterResolutionSection>();
+  for (const section of sections) {
+    sectionsByIndex.set(section.sectionIndex, section);
+  }
+
+  const candidates = candidateVariantsFor(variant);
+  for (let currentIndex = sectionIndex; currentIndex >= 0; currentIndex -= 1) {
+    const refs = sectionRefsFor(sectionsByIndex.get(currentIndex), kind);
+    if (!refs) continue;
+
+    for (const candidate of candidates) {
+      const refId = refs[candidate];
+      if (refId) {
+        return {
+          refId,
+          matchedSectionIndex: currentIndex,
+          matchedVariant: candidate,
+        };
+      }
+    }
+  }
+
+  return null;
+}