@storystick/react 0.0.0-stage → 0.2.0-rc.0

package/dist/rich-text.d.ts

@@ -0,0 +1,150 @@
+import { type ContentSource } from '@storystick/client/internal';
+import type { ComponentType, ReactNode } from 'react';
+import { type RichTextComponentTypes, type RichTextRenderContext, type RichTextRenderDiagnostic, type RichTextValue, type ResolvedLink } from '@storystick/types';
+import type { SliceComponentRegistry } from './slice-zone.js';
+import { type SliceContractRegistry, type SliceFallback, type SliceRenderFailureHandler } from './slice-render-failure.js';
+import { type SliceAnchor } from '@storystick/preview/provenance/slice-model';
+import { type PreviewProvenancePath, type PreviewProvenancePathCarrier } from './preview-provenance.js';
+/** A node in the ProseMirror JSON document tree. */
+export interface RichTextNode {
+    type: string;
+    attrs?: Record<string, unknown>;
+    content?: RichTextNode[];
+    text?: string;
+    marks?: RichTextMark[];
+}
+/** An inline mark on a text node. */
+export interface RichTextMark {
+    type: string;
+    attrs?: Record<string, unknown>;
+}
+export interface RichTextBlockComponentProps {
+    children: ReactNode;
+    text?: string;
+    /** Canonical section id authored on this heading, when present. */
+    id?: string;
+    context: RichTextRenderContext;
+}
+export interface RichTextCodeComponentProps extends RichTextBlockComponentProps {
+    language?: string;
+}
+export interface RichTextOrderedListComponentProps {
+    children: ReactNode;
+    start?: number;
+}
+export interface RichTextListComponentProps {
+    children: ReactNode;
+}
+export interface RichTextMarkComponentProps {
+    children: ReactNode;
+    context: RichTextRenderContext;
+}
+export interface RichTextLinkMarkComponentProps extends RichTextMarkComponentProps {
+    link: ResolvedLink;
+    title?: string;
+}
+export type RichTextCustomMarkComponentProps<TValue = undefined> = RichTextMarkComponentProps & (TValue extends undefined ? Record<never, never> : {
+    value: TValue;
+});
+type RichTextDefinitionOf<T> = NonNullable<T> extends RichTextValue<string, boolean, infer TComponents> ? TComponents : NonNullable<T> extends RichTextComponentTypes ? NonNullable<T> : RichTextComponentTypes;
+type RichTextCustomMarksOf<T> = RichTextDefinitionOf<NonNullable<T>>['marks'];
+type RichTextEmbedsOf<T> = RichTextDefinitionOf<NonNullable<T>>['embeds'];
+type RichTextCustomMarkRegistry<T> = {
+    readonly [TType in keyof RichTextCustomMarksOf<T>]: ComponentType<RichTextCustomMarkComponentProps<RichTextCustomMarksOf<T>[TType]>>;
+};
+type RichTextEmbedRegistry<T, TContext> = SliceComponentRegistry<RichTextEmbedsOf<T>, TContext>;
+type RegistrySection<TName extends 'marks' | 'embeds', TRegistry, TMode extends RichTextRenderMode> = TMode extends 'strict' ? {
+    readonly [TKey in TName]: TRegistry;
+} : {
+    readonly [TKey in TName]?: Partial<TRegistry>;
+};
+export type RichTextRenderMode = 'permissive' | 'strict';
+type BuiltinMarkRegistry = Partial<{
+    bold: ComponentType<RichTextMarkComponentProps>;
+    italic: ComponentType<RichTextMarkComponentProps>;
+    underline: ComponentType<RichTextMarkComponentProps>;
+    strike: ComponentType<RichTextMarkComponentProps>;
+    code: ComponentType<RichTextMarkComponentProps>;
+    link: ComponentType<RichTextLinkMarkComponentProps>;
+}>;
+export type RichTextComponents<T = RichTextComponentTypes, TMode extends RichTextRenderMode = 'permissive', TContext = unknown> = {
+    block?: Partial<{
+        paragraph: ComponentType<RichTextBlockComponentProps>;
+        h1: ComponentType<RichTextBlockComponentProps>;
+        h2: ComponentType<RichTextBlockComponentProps>;
+        h3: ComponentType<RichTextBlockComponentProps>;
+        h4: ComponentType<RichTextBlockComponentProps>;
+        h5: ComponentType<RichTextBlockComponentProps>;
+        h6: ComponentType<RichTextBlockComponentProps>;
+        blockquote: ComponentType<RichTextBlockComponentProps>;
+        code: ComponentType<RichTextCodeComponentProps>;
+        divider: ComponentType<Record<never, never>>;
+    }>;
+    list?: Partial<{
+        bullet: ComponentType<RichTextListComponentProps>;
+        ordered: ComponentType<RichTextOrderedListComponentProps>;
+    }>;
+    listItem?: Partial<{
+        bullet: ComponentType<RichTextListComponentProps>;
+        ordered: ComponentType<RichTextListComponentProps>;
+    }>;
+    hardBreak?: ComponentType<Record<never, never>>;
+} & RegistrySection<'marks', RichTextCustomMarkRegistry<T> & BuiltinMarkRegistry, TMode> & RegistrySection<'embeds', RichTextEmbedRegistry<T, TContext>, TMode>;
+interface RichTextBaseProps<TContent, TMode extends RichTextRenderMode, TContext> {
+    /** Richtext content — JSON string or parsed ProseMirror document. */
+    content: TContent;
+    /** Advanced owner for raw richtext; SDK values already carry their source. */
+    source?: ContentSource;
+    /** One semantic registry for blocks, lists, marks and embeds. */
+    components?: RichTextComponents<TContent, TMode, TContext>;
+    /** Strict requires complete custom mark/embed registries at compile time. */
+    mode?: TMode;
+    /** Framework-neutral diagnostics for malformed or unknown renderer input. */
+    onDiagnostic?: (diagnostic: RichTextRenderDiagnostic) => void;
+    /** Context passed to every embed component (same as SliceZone). */
+    context?: TContext;
+    /** Customer-owned fallback for malformed or non-renderable slice embeds. */
+    sliceFallback?: SliceFallback;
+    /** Runtime variation IDs generated from the resolved Story schema. */
+    contracts?: SliceContractRegistry;
+    /** Local observability hook shared with SliceZone. */
+    onRenderFailure?: SliceRenderFailureHandler;
+    /**
+     * Preview-only edit-binding attrs keyed by rich-text text-node path. When
+     * present, RichText wraps matching text nodes in DOM spans carrying data-ss-p.
+     * Same object the SliceZone hands each slice as `bindings`.
+     */
+    bindings?: PreviewProvenancePathCarrier;
+    /** Path to this richtext field inside the owning provenance carrier. */
+    provenancePath?: PreviewProvenancePath;
+    /** Preview-only owning rich-text field for sliceEmbed anchoring. */
+    sliceField?: string;
+    /** Preview-only ancestry when this rich text is rendered inside a slice zone. */
+    parentAnchors?: ReadonlyArray<SliceAnchor>;
+    /** Preview-only numeric visual path of the parent slice. */
+    parentPath?: string;
+    /** CSS class for wrapper div — if omitted, renders a React fragment. */
+    className?: string;
+    /** Fallback content when richtext is empty or null. */
+    fallback?: ReactNode;
+}
+export type RichTextProps<TContent = unknown, TMode extends RichTextRenderMode = 'permissive', TContext = unknown> = RichTextBaseProps<TContent, TMode, TContext> & (TMode extends 'strict' ? {
+    mode: 'strict';
+    components: RichTextComponents<TContent, 'strict', TContext>;
+} : {
+    mode?: 'permissive';
+});
+export type RichTextInlineProps<TContent extends RichTextValue<string, true, RichTextComponentTypes>, TMode extends RichTextRenderMode = 'permissive', TContext = unknown> = Omit<RichTextProps<TContent | null | undefined, TMode, TContext>, 'className' | 'content'> & {
+    content: TContent | null | undefined;
+};
+declare function RichTextRoot<TContent = unknown, TMode extends RichTextRenderMode = 'permissive', TContext = unknown>(props: RichTextProps<TContent, TMode, TContext>): ReactNode;
+declare function RichTextInline<TContent extends RichTextValue<string, true, RichTextComponentTypes>, TMode extends RichTextRenderMode = 'permissive', TContext = unknown>(props: RichTextInlineProps<TContent, TMode, TContext>): ReactNode;
+export declare const RichText: typeof RichTextRoot & {
+    Inline: typeof RichTextInline;
+};
+/**
+ * Extract plain text from richtext content.
+ * Handles both JSON string and parsed ProseMirror document.
+ */
+export declare function toText(content: unknown, separator?: string): string;
+export {};