Core API

All runtime functions, constants, classes and types below are exported from @page-sections/core. The package has no runtime dependencies, DOM requirement or rendering implementation. Svelte re-exports its types only.

resolvePageLayout(input: ResponsiveLayoutInput) returns { layout, content: { x, width }, menu: { x, y, width, height } }. It accounts for a reserved scrollbar and safe-area insets while classifying the original viewport width. The host owns those measurements; native Navigation assumes a full-width containing block.

resolveMenuOffset(scrollY: number, fixed = false) returns zero until 112px, then 112 - scrollY; fixed mode always returns zero.

For resolveCardLayout, s/m/l request 2/2/4 columns, except l uses 3 on the s grid. CardLayoutOptions accepts mediaAspect (3/2 default; also 4/3 or 1/1), mediaFit (contain default or cover), and reserveEyebrow (false default, ignored for S). Derive reserveEyebrow from the entire collection, as the Svelte collections do. Width comes from contentSpanWidth; mediaFrame.height is width divided by the selected ratio. Text height is (rows + eyebrowRows) * lineHeight + 2 * cardTextInset.block; total height is mediaFrame.height + textHeight. The media rectangle is inset by 8px for contain (clamped to available space), or fills mediaFrame for cover. These are default catalog measurements, not measurements of arbitrary CSS overrides or editorial copy. Observe the actual CardElements.media rectangle when attaching a renderer.

import {
  resolveContentGrid,
  contentSpanWidth,
  resolveCardLayout
} from '@page-sections/core';
const grid = resolveContentGrid(840);
console.log(grid.size, grid.columns, contentSpanWidth(840, 3)); // m, 8, 293
const card = resolveCardLayout(840, 'm');
console.log(card.width, card.height, card.media);

new SectionRegistry(changed?: () => void) creates a navigation registry. SECTION_REGISTRY is its exported context-key symbol, not a singleton registry.

Registration checks nonblank titles, IDs matching ^[a-z][a-z0-9-]*$, and page-local uniqueness. Changes call the callback. Updating unchanged metadata emits nothing. Unregister is idempotent, and subsequent updates on that handle do nothing. The registry stores id/title only, not content. Create one per page/request; Svelte ContentPage handles this automatically.

import { SectionRegistry } from '@page-sections/core';
const registry = new SectionRegistry();
const handle = registry.register({ id: 'intro', title: 'Introduction' });
handle.update({ id: 'intro', title: 'Start here' });
console.log(registry.sections);
handle.unregister();

normalizeSectionBackground(background: SectionBackground | undefined, context: SectionBackgroundContext = {}): ResolvedSectionBackground returns effective background values. context.pageKind?: 'content' | 'detail'; detail forces standard size. Svelte Section inherits pageKind from SectionSurfaceGroup and forwards it to the normalizer. Its optional onDiagnostic callback receives deduplicated diagnostics.

ResolvedSectionBackground has color: SectionBackgroundColor, size: standard/full, gradient: boolean, cssBackground: string and optional diagnostic: SectionBackgroundDiagnostic.

SectionBackgroundDiagnostic fields: code (gradient-requires-full-background), message: string, requestedColor: SectionBackgroundColor, requestedSize: standard/full, pageKind: content/detail/undefined, effectiveColor: transparent/standard/muted. Gradients with an effective standard size resolve to their end color.

createSectionBackgroundNormalizer(report?: (diagnostic: SectionBackgroundDiagnostic) => void) returns (background, context) => ResolvedSectionBackground. Unlike the direct function, the returned function's context argument is required (pass {}). It reports each requested-color/size/pageKind combination once per normalizer instance. No global state or automatic console logger is used.

import { createSectionBackgroundNormalizer } from '@page-sections/core';
const normalize = createSectionBackgroundNormalizer((diagnostic) =>
  console.warn(diagnostic.message)
);
const background = normalize(
  { color: 'standardToMuted', size: 'full' },
  { pageKind: 'content' }
);
console.log(background.cssBackground);

new SectionSurfaceRegistry(changed?: () => void) tracks presentation order. SECTION_SURFACES is the exported context-key symbol.

• register(surface: Pick<ResolvedSectionBackground, 'color' | 'size'>) returns a numeric id, update(next) and unregister(). IDs increase within that instance.
• order(ids: readonly number[]) deduplicates known IDs and appends unspecified registrations.
• corners returns { id: number; top: boolean; bottom: boolean }[]. Standard nontransparent neighbors join regardless of color; transparent/full surfaces break the group.
• Updates after unregister do nothing. A changed callback runs when registration, surface values or order change.

The input alias Surface is internal and is not a named package export. Use the structural Pick type above. See Section Backgrounds and Surface Groups.

themeStyle(theme: PageTheme = {}): string maps recognized fields to semicolon-separated --ps-* declarations. Unknown keys or values containing ;, {, }, < or > throw. This prevents additional declaration injection but does not validate arbitrary CSS grammar. Defaults to an empty string; palette defaults live in CSS.

safeHref(href: string | undefined): string | undefined returns undefined for unsupported URI schemes; permits http, https, mailto, tel and strings without a scheme. It strips control/space characters for the scheme check but returns the original accepted string. It is not URL normalization, domain allowlisting or comprehensive untrusted-content validation.

Every public content type is covered here or on its linked component page:

There is no runtime JSON schema/validator export. Applications validate externally supplied content. See CSS Variables and Layout Tokens for all token values.

• HeadingLevel: 1 through 6; inherited by nested sections and cards.
• PageKind: content or detail; controls background normalization and large detail-pane corners.
• CardVariant: catalog or editorial.
• CardMediaAspect: 3/2, 4/3 or 1/1; applies to the media frame only.
• CardMediaFit: contain or cover; independent from the frame ratio.
• CardLayoutOptions: mediaAspect, mediaFit and reserveEyebrow for catalog measurements.
• InlineText: string or InlineRun array. InlineRun: text/strong/emphasis/code with text, link with text/href, or break.
• ContentAction: label, href, optional variant (primary, secondary, text).
• RichTextContentData: either body with optional format, or blocks; the two sources are mutually exclusive.
• RichTextBlock: paragraph (text, optional variant default/lead/muted), address (name, lines), list (items, optional ordered), panel (optional title/tone/actions, blocks). Panels can nest.
• PanelSectionData: shared SectionDefinition, type panel, required blocks, optional tone and actions.

See structured text, panels and shared layout reference.

SurfaceTone is the shared standard | muted surface selection for Card.tone, collection cardTone, PanelSectionData.tone and structured panel blocks. The selection follows the active theme and does not change the surrounding SectionBackground.

CodeData contains source and presentation options. CodeSectionData adds section metadata and the code discriminator. CodeToken and HighlightedCode describe optional derived syntax tokens. See the complete code reference for fields, defaults and examples.

resolveNavigation(tree, location: NavigationLocation) derives active items, the current root, sidebarItems and breadcrumbs from a tree of page links. NavigationLocation accepts pathname or currentId. MenuItem requires href; optional icon is an application-owned key.

resolveContentPageLayout(input) extends ResponsiveLayoutInput with leftSidebar, showContentMenu and contentMenuDetached booleans (default false). It returns the independent menu rectangle, content rectangle and optional sidebar rectangles. Safe-area and scrollbar insets are included.

resolveActiveContentSection(sections: ContentSectionBounds[], readingTop, readingBottom, scrollY, maxScrollY) returns the active ID or undefined. ContentSectionBounds contains id, top and bottom. Coordinates are relative to the reading viewport; the function has no DOM dependency.