@micropress/theme-sdk 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,618 @@
+/**
+ * Result of html`` tagged template.
+ */
+interface HtmlResult {
+    html: string;
+    toString(): string;
+}
+/**
+ * Escape HTML entities for safe insertion.
+ */
+declare function escapeHtml(unsafe: string): string;
+/**
+ * Tagged template for HTML.
+ * Automatically escapes interpolated values unless they're HtmlResult.
+ *
+ * @example
+ * ```ts
+ * const name = '<script>alert("xss")</script>';
+ * html`<div>${name}</div>` // Safe: <div>&lt;script&gt;...</div>
+ *
+ * const inner = html`<span>safe</span>`;
+ * html`<div>${inner}</div>` // Nested HTML preserved
+ * ```
+ */
+declare function html(strings: TemplateStringsArray, ...values: unknown[]): HtmlResult;
+/**
+ * Mark raw HTML as safe (use carefully!).
+ *
+ * @example
+ * ```ts
+ * const trusted = raw('<b>trusted content</b>');
+ * html`<div>${trusted}</div>`
+ * ```
+ */
+declare function raw(htmlString: string): HtmlResult;
+/**
+ * Join multiple HTML results.
+ */
+declare function join(items: HtmlResult[], separator?: string): HtmlResult;
+/**
+ * Conditional HTML - returns empty if condition is false.
+ */
+declare function when(condition: boolean, content: HtmlResult | string): HtmlResult;
+/**
+ * CSS tagged template - just returns the string.
+ * Useful for syntax highlighting in editors.
+ */
+declare function css(strings: TemplateStringsArray, ...values: unknown[]): string;
+
+/** Mark types for inline text formatting */
+type MarkType = 'bold' | 'italic' | 'code' | 'strike' | 'link';
+/** A formatting mark applied to text */
+interface TextMark {
+    type: MarkType;
+    attrs?: {
+        href?: string;
+        target?: string;
+    };
+}
+/** Inline text content with optional formatting */
+interface TextBlock {
+    type: 'text';
+    content: string;
+    marks?: TextMark[];
+}
+/** A paragraph containing text */
+interface ParagraphBlock {
+    type: 'paragraph';
+    children: TextBlock[];
+}
+/** A heading (h1-h6) */
+interface HeadingBlock {
+    type: 'heading';
+    level: 1 | 2 | 3 | 4 | 5 | 6;
+    children: TextBlock[];
+}
+/** A blockquote containing nested blocks */
+interface BlockquoteBlock {
+    type: 'blockquote';
+    children: ContentBlock[];
+}
+/** A code block with optional language */
+interface CodeBlock {
+    type: 'codeBlock';
+    code: string;
+    language?: string;
+}
+/** A horizontal rule divider */
+interface HorizontalRuleBlock {
+    type: 'horizontalRule';
+}
+/** A hard line break */
+interface HardBreakBlock {
+    type: 'hardBreak';
+}
+/** An unordered list */
+interface BulletListBlock {
+    type: 'bulletList';
+    items: ListItemBlock[];
+}
+/** An ordered list */
+interface OrderedListBlock {
+    type: 'orderedList';
+    items: ListItemBlock[];
+    start?: number;
+}
+/** A list item containing blocks */
+interface ListItemBlock {
+    type: 'listItem';
+    children: ContentBlock[];
+}
+/** An image */
+interface ImageBlock {
+    type: 'image';
+    src: string;
+    alt: string;
+    title?: string;
+    width?: number;
+    height?: number;
+}
+/** A video embed */
+interface VideoBlock {
+    type: 'video';
+    src: string;
+    poster?: string;
+    controls?: boolean;
+}
+/** An external embed (YouTube, Vimeo, etc.) */
+interface EmbedBlock {
+    type: 'embed';
+    url: string;
+    embedType: 'youtube' | 'vimeo' | 'twitter' | 'generic';
+}
+/** A container for layout purposes */
+interface ContainerBlock {
+    type: 'container';
+    children: ContentBlock[];
+    layout?: 'stack' | 'row' | 'grid';
+    gap?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+}
+/** A card container */
+interface CardBlock {
+    type: 'card';
+    children: ContentBlock[];
+    variant?: 'default' | 'outlined' | 'elevated';
+}
+/** A page section */
+interface SectionBlock {
+    type: 'section';
+    children: ContentBlock[];
+    id?: string;
+}
+/** An accordion/expandable section */
+interface AccordionBlock {
+    type: 'accordion';
+    title: string;
+    children: ContentBlock[];
+    defaultOpen?: boolean;
+}
+/** A tab item for tabbed content */
+interface TabItem {
+    label: string;
+    content: ContentBlock[];
+}
+/** Tabbed content container */
+interface TabsBlock {
+    type: 'tabs';
+    items: TabItem[];
+}
+/** A modal dialog */
+interface ModalBlock {
+    type: 'modal';
+    trigger: string;
+    title?: string;
+    content: ContentBlock[];
+}
+/** A button */
+interface ButtonBlock {
+    type: 'button';
+    label: string;
+    href?: string;
+    variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
+    action?: string;
+}
+/** A hyperlink */
+interface LinkBlock {
+    type: 'link';
+    href: string;
+    children: TextBlock[];
+    target?: '_blank' | '_self';
+}
+/** A data table */
+interface TableBlock {
+    type: 'table';
+    headers: string[];
+    rows: string[][];
+    caption?: string;
+}
+/** A status badge */
+interface BadgeBlock {
+    type: 'badge';
+    text: string;
+    variant?: 'default' | 'primary' | 'success' | 'warning' | 'error';
+}
+/** An alert box */
+interface AlertBlock {
+    type: 'alert';
+    message: string;
+    alertType: 'info' | 'warning' | 'error' | 'success';
+}
+/** An icon */
+interface IconBlock {
+    type: 'icon';
+    name: string;
+    size?: 'sm' | 'md' | 'lg';
+}
+/** A form input */
+interface InputBlock {
+    type: 'input';
+    inputType: 'text' | 'email' | 'password' | 'number' | 'tel' | 'url';
+    label: string;
+    name: string;
+    placeholder?: string;
+    required?: boolean;
+}
+/** A textarea */
+interface TextareaBlock {
+    type: 'textarea';
+    label: string;
+    name: string;
+    rows?: number;
+    placeholder?: string;
+    required?: boolean;
+}
+/** A select dropdown */
+interface SelectBlock {
+    type: 'select';
+    label: string;
+    name: string;
+    options: {
+        value: string;
+        label: string;
+    }[];
+    required?: boolean;
+}
+/** A checkbox */
+interface CheckboxBlock {
+    type: 'checkbox';
+    label: string;
+    name: string;
+    checked?: boolean;
+}
+/** A custom or unknown block type (for plugin extensibility) */
+interface CustomBlock {
+    type: 'custom';
+    customType: string;
+    attrs?: Record<string, unknown>;
+    children?: ContentBlock[];
+    content?: string;
+}
+/** All content blocks that can appear in the document body */
+type ContentBlock = TextBlock | ParagraphBlock | HeadingBlock | BlockquoteBlock | CodeBlock | HorizontalRuleBlock | HardBreakBlock | BulletListBlock | OrderedListBlock | ListItemBlock | ImageBlock | VideoBlock | EmbedBlock | ContainerBlock | CardBlock | SectionBlock | AccordionBlock | TabsBlock | ModalBlock | ButtonBlock | LinkBlock | TableBlock | BadgeBlock | AlertBlock | IconBlock | InputBlock | TextareaBlock | SelectBlock | CheckboxBlock | CustomBlock;
+/** Building block - alias for ContentBlock for clarity in API */
+type BuildingBlock = ContentBlock;
+/** Helper type to extract block by type */
+type BlockOfType<T extends ContentBlock['type']> = Extract<ContentBlock, {
+    type: T;
+}>;
+
+/** The type of content being rendered */
+type ContentType = 'page' | 'news-article' | 'news-list';
+/** Base content interface with common fields */
+interface BaseContentDTO {
+    /** Page/article title */
+    title: string;
+    /** Content type discriminator */
+    contentType: ContentType;
+}
+/** A regular page's content */
+interface PageContentDTO extends BaseContentDTO {
+    contentType: 'page';
+    /** Content blocks to render */
+    blocks: BuildingBlock[];
+}
+/** A back navigation link */
+interface BackLinkDTO {
+    label: string;
+    href: string;
+}
+/** A news article's content */
+interface NewsArticleDTO extends BaseContentDTO {
+    contentType: 'news-article';
+    /** Content blocks to render */
+    blocks: BuildingBlock[];
+    /** Publication date (ISO string for formatting) */
+    publishedAt: string;
+    /** Author name */
+    author?: string;
+    /** Link back to news list */
+    backLink: BackLinkDTO;
+}
+/** A news card in the news list */
+interface NewsCardDTO {
+    /** Article title */
+    title: string;
+    /** Article excerpt/preview */
+    excerpt?: string;
+    /** Publication date (ISO string) */
+    publishedAt: string;
+    /** Link to full article */
+    href: string;
+    /** Whether this is a featured article */
+    featured?: boolean;
+    /** Cover image URL */
+    image?: string;
+    /** Category label (e.g., "News", "Events") */
+    category?: string;
+    /** Estimated reading time in minutes */
+    readingTime?: number;
+}
+/** A news list page's content */
+interface NewsListDTO extends BaseContentDTO {
+    contentType: 'news-list';
+    /** The news cards to display */
+    items: NewsCardDTO[];
+}
+/** All content types that can be rendered in the main content area */
+type ContentDTO = PageContentDTO | NewsArticleDTO | NewsListDTO;
+/** Check if content is a regular page */
+declare function isPageContent(content: ContentDTO): content is PageContentDTO;
+/** Check if content is a news article */
+declare function isNewsArticle(content: ContentDTO): content is NewsArticleDTO;
+/** Check if content is a news list */
+declare function isNewsList(content: ContentDTO): content is NewsListDTO;
+
+/** SEO and social metadata for a page */
+interface MetaDTO {
+    description?: string;
+    keywords?: string[];
+    ogTitle?: string;
+    ogDescription?: string;
+    ogImage?: string;
+    canonical?: string;
+    noIndex?: boolean;
+    jsonLd: object[];
+}
+/** Logo configuration */
+interface LogoDTO {
+    src: string;
+    alt: string;
+}
+/** Site header configuration */
+interface HeaderDTO {
+    siteName: string;
+    tagline?: string;
+    logo?: LogoDTO;
+    showMenuToggle: boolean;
+}
+/** A navigation item */
+interface NavItemDTO {
+    label: string;
+    href: string;
+    active: boolean;
+    children?: NavItemDTO[];
+}
+/** Navigation configuration */
+interface NavigationDTO {
+    items: NavItemDTO[];
+}
+/** A single breadcrumb item */
+interface BreadcrumbDTO {
+    /** Display label */
+    label: string;
+    /** Link URL (undefined = current page, no link) */
+    href?: string;
+}
+/** Breadcrumb trail configuration */
+interface BreadcrumbsDTO {
+    /** Breadcrumb items from root to current */
+    items: BreadcrumbDTO[];
+}
+/** A footer link */
+interface FooterLinkDTO {
+    label: string;
+    href: string;
+}
+/** Site footer configuration */
+interface FooterDTO {
+    copyright: string;
+    year: number;
+    links: FooterLinkDTO[];
+}
+/** A favicon or icon link */
+interface FaviconDTO {
+    rel: 'icon' | 'apple-touch-icon';
+    type?: string;
+    sizes?: string;
+    href: string;
+}
+/** Site-level configuration for theming */
+interface SiteConfigDTO {
+    siteName: string;
+    shortName: string;
+    description?: string;
+    themeColor?: string;
+    backgroundColor?: string;
+    language: string;
+}
+/** Full page document DTO */
+interface DocumentDTO {
+    /** HTML lang attribute */
+    lang: string;
+    /** Page title for <title> tag */
+    title: string;
+    /** Active theme identifier */
+    themeId: string;
+    /** SEO and social metadata */
+    meta: MetaDTO;
+    /** Header configuration */
+    header: HeaderDTO;
+    /** Navigation configuration */
+    navigation: NavigationDTO;
+    /** Main page content */
+    content: ContentDTO;
+    /** Footer configuration */
+    footer: FooterDTO;
+    /** Favicon and icon links */
+    favicons: FaviconDTO[];
+    /** External stylesheets to include */
+    styles: string[];
+    /** CSS custom properties to inject */
+    cssVariables: Record<string, string>;
+}
+
+interface ThemeBreakpoints {
+    sm?: string;
+    md?: string;
+    lg?: string;
+    xl?: string;
+}
+interface ThemeCustomizableField {
+    type: 'color' | 'font' | 'size' | 'select';
+    label: string;
+    default: string;
+    options?: string[];
+}
+interface ThemeManifest {
+    id: string;
+    name: string;
+    version: string;
+    description: string;
+    author: string;
+    homepage?: string;
+    breakpoints?: ThemeBreakpoints;
+    customizable?: Record<string, ThemeCustomizableField>;
+}
+interface InstalledTheme {
+    id: string;
+    version: string;
+    active: boolean;
+    installedAt: string;
+    installedBy: string;
+    customizations: Record<string, string>;
+    manifest: ThemeManifest;
+    updatedAt?: string;
+    updatedBy?: string;
+    releaseUrl?: string;
+}
+interface ThemeRegistryEntry {
+    id: string;
+    name: string;
+    description: string;
+    latestVersion: string;
+    author: string;
+    githubRepo: string;
+    releaseUrl: string;
+    previewUrl?: string;
+}
+
+/**
+ * Context passed to every render function.
+ * Contains everything you need to render content.
+ */
+interface RenderContext {
+    /** Render a child block */
+    render: (block: ContentBlock | BuildingBlock) => string;
+    /** Render multiple blocks */
+    renderAll: (blocks: (ContentBlock | BuildingBlock)[]) => string;
+    /** Site configuration */
+    site: {
+        name: string;
+        baseUrl: string;
+        currentPath?: string;
+    };
+}
+/**
+ * A render function takes data and context, returns HTML.
+ */
+type RenderFn<T> = (data: T, ctx: RenderContext) => string;
+/**
+ * A renderer object with optional styles and scripts.
+ */
+interface Renderer<T = unknown> {
+    render: RenderFn<T>;
+    styles?: () => string;
+    scripts?: () => string;
+}
+/**
+ * Shorthand type for block renderers.
+ */
+type BlockRenderer<T extends ContentBlock = ContentBlock> = Renderer<T>;
+/**
+ * Helper to create a typed renderer.
+ */
+declare function renderer<T>(fn: RenderFn<T>): Renderer<T>;
+declare function renderer<T>(options: Renderer<T>): Renderer<T>;
+
+/**
+ * All the components a theme can customize.
+ * Every component is optional - defaults are used for missing ones.
+ */
+interface ThemeRenderers {
+    document?: Renderer<DocumentDTO>;
+    header?: Renderer<HeaderDTO>;
+    navigation?: Renderer<NavigationDTO>;
+    footer?: Renderer<FooterDTO>;
+    article?: Renderer<PageContentDTO>;
+    newsArticle?: Renderer<NewsArticleDTO>;
+    newsList?: Renderer<NewsListDTO>;
+    newsCard?: Renderer<NewsCardDTO>;
+    blocks?: Partial<Record<ContentBlock['type'], Renderer<ContentBlock>>>;
+}
+/**
+ * Theme configuration.
+ */
+interface ThemeConfig {
+    /** Theme ID (must match manifest) */
+    id: string;
+    /** Theme display name */
+    name: string;
+    /** Theme version */
+    version: string;
+    /** CSS variables for customization */
+    variables?: Record<string, string>;
+}
+/**
+ * Complete theme definition.
+ */
+interface ThemeDefinition {
+    config: ThemeConfig;
+    renderers: ThemeRenderers;
+    /** Global styles for the theme */
+    styles?: string;
+    /** Global scripts for the theme */
+    scripts?: string;
+}
+/**
+ * Define a theme with custom renderers.
+ *
+ * @example
+ * ```ts
+ * import { defineTheme, html } from '@micropress/theme-sdk';
+ *
+ * export default defineTheme({
+ *   config: {
+ *     id: 'my-theme',
+ *     name: 'My Theme',
+ *     version: '1.0.0',
+ *   },
+ *   renderers: {
+ *     header: {
+ *       render: (data, ctx) => html`
+ *         <header class="my-header">
+ *           <h1>${data.siteName}</h1>
+ *         </header>
+ *       `.html,
+ *     },
+ *   },
+ * });
+ * ```
+ */
+declare function defineTheme(definition: ThemeDefinition): ThemeDefinition;
+/**
+ * Quick helper to define just a render function.
+ *
+ * @example
+ * ```ts
+ * const header = render<HeaderDTO>((data, ctx) => html`
+ *   <header>${data.siteName}</header>
+ * `.html);
+ * ```
+ */
+declare function render<T>(fn: RenderFn<T>): Renderer<T>;
+/**
+ * Quick helper to define a renderer with styles.
+ *
+ * @example
+ * ```ts
+ * const card = withStyles<CardDTO>(
+ *   (data, ctx) => html`<div class="card">${ctx.renderAll(data.children)}</div>`.html,
+ *   css`.card { padding: 1rem; }`
+ * );
+ * ```
+ */
+declare function withStyles<T>(fn: RenderFn<T>, styles: string): Renderer<T>;
+/**
+ * Quick helper to define a renderer with scripts.
+ */
+declare function withScripts<T>(fn: RenderFn<T>, scripts: string): Renderer<T>;
+/**
+ * Define a renderer with both styles and scripts.
+ */
+declare function withAssets<T>(fn: RenderFn<T>, options: {
+    styles?: string;
+    scripts?: string;
+}): Renderer<T>;
+
+export { type AccordionBlock, type AlertBlock, type BackLinkDTO, type BadgeBlock, type BaseContentDTO, type BlockOfType, type BlockRenderer, type BlockquoteBlock, type BreadcrumbDTO, type BreadcrumbsDTO, type BuildingBlock, type BulletListBlock, type ButtonBlock, type CardBlock, type CheckboxBlock, type CodeBlock, type ContainerBlock, type ContentBlock, type ContentDTO, type ContentType, type CustomBlock, type DocumentDTO, type EmbedBlock, type FaviconDTO, type FooterDTO, type FooterLinkDTO, type HardBreakBlock, type HeaderDTO, type HeadingBlock, type HorizontalRuleBlock, type HtmlResult, type IconBlock, type ImageBlock, type InputBlock, type InstalledTheme, type LinkBlock, type ListItemBlock, type LogoDTO, type MarkType, type MetaDTO, type ModalBlock, type NavItemDTO, type NavigationDTO, type NewsArticleDTO, type NewsCardDTO, type NewsListDTO, type OrderedListBlock, type PageContentDTO, type ParagraphBlock, type RenderContext, type RenderFn, type Renderer, type SectionBlock, type SelectBlock, type SiteConfigDTO, type TabItem, type TableBlock, type TabsBlock, type TextBlock, type TextMark, type TextareaBlock, type ThemeBreakpoints, type ThemeConfig, type ThemeCustomizableField, type ThemeDefinition, type ThemeManifest, type ThemeRegistryEntry, type ThemeRenderers, type VideoBlock, css, defineTheme, escapeHtml, html, isNewsArticle, isNewsList, isPageContent, join, raw, render, renderer, when, withAssets, withScripts, withStyles };