@riverbankcms/sdk 0.144.0 → 0.145.0

package/dist/_dts/theme-core/src/site-styles/sectionBoundaryComposition.d.ts

@@ -0,0 +1,95 @@
+import { type ThemeColorToken } from '../tokens/themeColorTokens';
+import type { DecorativeTransitionIntent } from './transitionCatalogue';
+import { type FrameKind } from './types';
+/**
+ * What one side of a join offers a boundary to paint with. Only theme tokens
+ * paint: media, gradients and literal colours cannot be matched by a flat
+ * shape, so they are unpainted and the boundary draws inside the other side.
+ */
+export type BoundaryEndpoint = Readonly<{
+    kind: 'paint';
+    token: ThemeColorToken;
+}> | Readonly<{
+    kind: 'unpainted';
+    reason: 'media' | 'gradient' | 'literal-color';
+}>;
+export type BoundaryComposition = Readonly<{
+    kind: 'paint-to-paint';
+    from: ThemeColorToken;
+    to: ThemeColorToken;
+}> | Readonly<{
+    kind: 'unpainted-to-paint';
+    to: ThemeColorToken;
+}> | Readonly<{
+    kind: 'paint-to-unpainted';
+    from: ThemeColorToken;
+}>;
+/**
+ * What composition needs to know about one side of a join, read from the
+ * content that finally renders: what the section paints with and the frame it
+ * draws.
+ */
+export type SectionFacts = Readonly<{
+    endpoint: BoundaryEndpoint;
+    frame: FrameKind;
+}>;
+export type BoundaryNotShownReason = 'both-unpainted' | 'flush-panel';
+export type BoundaryOutcome = Readonly<{
+    kind: 'shown';
+    composition: BoundaryComposition;
+}> | Readonly<{
+    kind: 'not-shown';
+    reason: BoundaryNotShownReason;
+}>;
+/**
+ * `centred` straddles the join; `previous` sits inside the previous section,
+ * anchored to its bottom; `next` sits inside the next section, anchored to its
+ * top and mirrored vertically.
+ */
+export type BoundaryPlacement = 'centred' | 'previous' | 'next';
+export type BoundaryLayout = Readonly<{
+    placement: BoundaryPlacement;
+    /**
+     * Extra section padding the boundary needs, as CSS lengths. `before` is
+     * reserved inside the previous section (above the join) and `after` inside
+     * the next section (below it). Null means no reserve on that side.
+     */
+    reserves: Readonly<{
+        before: string | null;
+        after: string | null;
+    }>;
+    paint: Readonly<{
+        band: ThemeColorToken | null;
+        shape: ThemeColorToken;
+    }>;
+}>;
+/**
+ * Classifies a section from its final render content. `_sectionStyles`
+ * already holds the effective background (Look default, page-design override
+ * and block-authored media merged by `resolveSectionBackground`), so this only
+ * reads it and never re-decides precedence. A missing or unparseable
+ * background is the page background, as it is for the renderer.
+ */
+export declare function boundaryEndpointForSectionContent(content: Record<string, unknown>): BoundaryEndpoint;
+/**
+ * Reads both facts from final render content in one place. `_frameStyles` is
+ * the compiled frame; content without one (no page design, an SDK block)
+ * draws a plain frame.
+ */
+export declare function sectionFactsForContent(content: Record<string, unknown>): SectionFacts;
+/**
+ * The frame rule: a flush panel owns the edge it runs to, so no break is
+ * drawn next to one. The single home for this rule; the generated
+ * pipeline's budget and the site-style lab ask it with their plan frames.
+ */
+export declare function frameNotShownReason(previous: FrameKind, next: FrameKind): Extract<BoundaryNotShownReason, 'flush-panel'> | null;
+/**
+ * Decides whether and how a join draws. The frame rule wins before paint is
+ * considered; two unpainted sides show nothing.
+ */
+export declare function composeBoundary(previous: SectionFacts, next: SectionFacts): BoundaryOutcome;
+/**
+ * Placement, reserves and paint for a shown boundary, derived from the
+ * composition and the catalogue's metrics for the treatment.
+ */
+export declare function boundaryLayout(intent: DecorativeTransitionIntent, composition: BoundaryComposition): BoundaryLayout;