@aureuma/svelta 0.1.1 → 0.4.0

package/packages/core/dist/experience/patterns.js

@@ -0,0 +1,98 @@
+export const DEFAULT_DOCS_PATTERN_CONFIG = {
+    kind: 'docs',
+    brandName: 'svelta',
+    productName: 'Documentation',
+    title: 'Structured docs with first-class markdown ergonomics.',
+    description: 'Ship Mintlify-style docs UX with sectioned navigation, command-palette search, right-rail table of contents, and content feedback loops.',
+    defaultSectionLabel: 'Guides',
+    sectionOrder: ['overview', 'getting-started', 'guides', 'api', 'reference'],
+    navigation: {
+        header: [
+            { label: 'Docs', href: '/docs' },
+            { label: 'Blog', href: '/blog' }
+        ],
+        footer: [
+            { label: 'Overview', href: '/docs/overview' },
+            { label: 'Getting Started', href: '/docs/getting-started' }
+        ]
+    },
+    search: {
+        enabled: true,
+        placeholder: 'Search documentation...',
+        shortcut: 'Ctrl K'
+    },
+    toc: {
+        enabled: true,
+        title: 'On This Page'
+    },
+    feedback: {
+        enabled: true,
+        prompt: 'Was this page helpful?'
+    },
+    editLinkTemplate: 'https://github.com/Aureuma/svelta/blob/main/src/content/docs/:slug.md'
+};
+export const DEFAULT_BLOG_PATTERN_CONFIG = {
+    kind: 'blog',
+    brandName: 'svelta',
+    title: 'Editorial publishing with modern feed ergonomics.',
+    description: 'Publish markdown-driven updates with taxonomy, progressive pagination, author attribution, and RSS delivery.',
+    pageSize: 8,
+    maxPageSize: 24,
+    infiniteScroll: true,
+    showRss: true,
+    navigation: {
+        header: [
+            { label: 'Blog', href: '/blog' },
+            { label: 'Tags', href: '/blog/tags' },
+            { label: 'Archive', href: '/blog/archive' }
+        ],
+        footer: [
+            { label: 'All posts', href: '/blog' },
+            { label: 'Authors', href: '/blog/authors' },
+            { label: 'RSS', href: '/feed.xml' }
+        ]
+    }
+};
+export function createDocsPatternConfig(overrides) {
+    return {
+        ...DEFAULT_DOCS_PATTERN_CONFIG,
+        ...overrides,
+        kind: 'docs',
+        navigation: {
+            ...DEFAULT_DOCS_PATTERN_CONFIG.navigation,
+            ...(overrides?.navigation ?? {})
+        },
+        search: {
+            ...DEFAULT_DOCS_PATTERN_CONFIG.search,
+            ...(overrides?.search ?? {})
+        },
+        toc: {
+            ...DEFAULT_DOCS_PATTERN_CONFIG.toc,
+            ...(overrides?.toc ?? {})
+        },
+        feedback: {
+            ...DEFAULT_DOCS_PATTERN_CONFIG.feedback,
+            ...(overrides?.feedback ?? {})
+        }
+    };
+}
+export function createBlogPatternConfig(overrides) {
+    return {
+        ...DEFAULT_BLOG_PATTERN_CONFIG,
+        ...overrides,
+        kind: 'blog',
+        navigation: {
+            ...DEFAULT_BLOG_PATTERN_CONFIG.navigation,
+            ...(overrides?.navigation ?? {})
+        }
+    };
+}
+export function createSveltaPatternConfig(overrides) {
+    return {
+        docs: createDocsPatternConfig(overrides?.docs),
+        blog: createBlogPatternConfig(overrides?.blog)
+    };
+}
+export function resolveDocsEditUrl(config, slug) {
+    return config.editLinkTemplate.replaceAll(':slug', slug);
+}

package/packages/core/dist/index.d.ts

@@ -8,4 +8,13 @@ export { default as MorePosts } from './components/blog/MorePosts.svelte';
 export { default as ShareButtons } from './components/blog/ShareButtons.svelte';
 export { default as SummaryCard } from './components/blog/SummaryCard.svelte';
 export { default as TagTabs } from './components/blog/TagTabs.svelte';
-export type { BlogAuthor, BlogCategory, BlogPost, BlogPostFull, BlogPostWithContent, BlogTag } from './types/blog';
+export { default as DocsPager } from './components/docs/DocsPager.svelte';
+export { default as DocsSectionGrid } from './components/docs/DocsSectionGrid.svelte';
+export { default as DocsShell } from './components/docs/DocsShell.svelte';
+export { default as DocsSidebar } from './components/docs/DocsSidebar.svelte';
+export { createExperienceCatalog, parseExperienceKind } from './experience';
+export { createBlogPatternConfig, createDocsPatternConfig, createSveltaPatternConfig, DEFAULT_BLOG_PATTERN_CONFIG, DEFAULT_DOCS_PATTERN_CONFIG, resolveDocsEditUrl } from './experience';
+export type { BlogAuthor, BlogAuthorSummary, BlogArchiveGroup, BlogCategory, BlogPost, BlogPostFull, BlogPostWithContent, BlogTag, SharePlatform } from './types/blog';
+export type { DocsPage, DocsPageFull, DocsPageWithContent, DocsSection, DocsSidebarSection } from './types/docs';
+export type { ExperienceCatalog, ExperienceDefinition, ExperienceKind } from './types/experience';
+export type { SveltaBlogPatternConfig, SveltaDocsPatternConfig, SveltaNavItem, SveltaPatternConfig } from './types/experience';

package/packages/core/dist/index.js

@@ -9,3 +9,9 @@ export { default as MorePosts } from './components/blog/MorePosts.svelte';
 export { default as ShareButtons } from './components/blog/ShareButtons.svelte';
 export { default as SummaryCard } from './components/blog/SummaryCard.svelte';
 export { default as TagTabs } from './components/blog/TagTabs.svelte';
+export { default as DocsPager } from './components/docs/DocsPager.svelte';
+export { default as DocsSectionGrid } from './components/docs/DocsSectionGrid.svelte';
+export { default as DocsShell } from './components/docs/DocsShell.svelte';
+export { default as DocsSidebar } from './components/docs/DocsSidebar.svelte';
+export { createExperienceCatalog, parseExperienceKind } from './experience';
+export { createBlogPatternConfig, createDocsPatternConfig, createSveltaPatternConfig, DEFAULT_BLOG_PATTERN_CONFIG, DEFAULT_DOCS_PATTERN_CONFIG, resolveDocsEditUrl } from './experience';

package/packages/core/dist/server/blog.d.ts

@@ -1,4 +1,4 @@
-import type { BlogAuthor, BlogCategory, BlogPost, BlogPostFull, BlogPostWithContent, BlogTag } from '../types/blog';
+import type { BlogAuthor, BlogAuthorSummary, BlogArchiveGroup, BlogCategory, BlogPost, BlogPostFull, BlogPostWithContent, BlogTag } from '../types/blog';
 import { z } from 'zod';
 declare const frontmatterSchema: z.ZodObject<{
     title: z.ZodString;
@@ -27,6 +27,7 @@ export type BlogCreateConfig = {
     rawModules: Record<string, () => Promise<string>>;
     getAuthor: (id: string) => BlogAuthor;
     categoryOrder?: string[];
+    allowMultipleTags?: boolean;
     mapFrontmatter?: BlogFrontmatterAdapter;
 };
 export type MarkdownRenderer = (markdown: string) => string | Promise<string>;
@@ -34,6 +35,7 @@ export type RawBlogCreateConfig = {
     rawModules: Record<string, () => Promise<string>>;
     getAuthor: (id: string) => BlogAuthor;
     categoryOrder?: string[];
+    allowMultipleTags?: boolean;
     mapFrontmatter?: BlogFrontmatterAdapter;
     renderMarkdown?: MarkdownRenderer;
 };
@@ -83,6 +85,17 @@ export declare function createBlog(config: BlogCreateConfig): {
     getPostBySlug: (slug: string) => Promise<BlogPostFull | null>;
     getCategories: () => Promise<BlogCategory[]>;
     pickHero: (posts?: BlogPost[]) => Promise<BlogPost>;
+    getAllTags: () => Promise<BlogTag[]>;
+    getPostsByTag: (tagSlug: string) => Promise<BlogPost[]>;
+    getPostsByAuthor: (authorId: string) => Promise<BlogPost[]>;
+    getAllAuthors: () => Promise<BlogAuthor[]>;
+    getAuthorSummaries: () => Promise<BlogAuthorSummary[]>;
+    getArchiveGroups: () => Promise<BlogArchiveGroup[]>;
+    getAdjacentPosts: (slug: string) => Promise<{
+        previous: BlogPost | null;
+        next: BlogPost | null;
+    }>;
+    getRelatedPosts: (slug: string, limit?: number) => Promise<BlogPost[]>;
 };
 export declare function parseVivaBlogFrontmatter(data: unknown): VivaBlogFrontmatter;
 export declare function parseVivaAuthorFrontmatter(data: unknown): VivaAuthorFrontmatter;

package/packages/core/dist/server/blog.js

@@ -78,7 +78,7 @@ function normalizeCategory(label) {
 }
 function parseISODate(date) {
     // Prefer stable UTC parsing for YYYY-MM-DD.
-    if (/^\\d{4}-\\d{2}-\\d{2}$/.test(date)) {
+    if (/^\d{4}-\d{2}-\d{2}$/.test(date)) {
         const d = new Date(`${date}T00:00:00Z`);
         if (!Number.isNaN(d.getTime()))
             return d;
@@ -100,6 +100,11 @@ const fmtShort = new Intl.DateTimeFormat('en-US', {
     year: 'numeric',
     timeZone: 'UTC'
 });
+const fmtArchive = new Intl.DateTimeFormat('en-US', {
+    month: 'long',
+    year: 'numeric',
+    timeZone: 'UTC'
+});
 function stripForExcerpt(markdown) {
     return (markdown
         // remove fenced code blocks
@@ -133,8 +138,14 @@ function minutesToLabels(minutes) {
         long: `${m} ${unit} read`
     };
 }
+function normalizeTags(tags, categoryLabel, allowMultipleTags) {
+    const cleaned = (tags ?? []).map((tag) => tag.trim()).filter(Boolean);
+    const resolved = cleaned.length > 0 ? cleaned : [categoryLabel];
+    return allowMultipleTags ? resolved : [resolved[0]];
+}
 export function createBlog(config) {
     const categoryOrder = config.categoryOrder ?? DEFAULT_CATEGORY_ORDER;
+    const allowMultipleTags = config.allowMultipleTags ?? false;
     let cachedMetaIndex = null;
     let cachedFullIndex = null;
     let cachedSlugToPath = null;
@@ -178,13 +189,14 @@ export function createBlog(config) {
             const dateObj = parseISODate(metadata.date);
             const rt = minutesToLabels(readingTime(content).minutes);
             const category = normalizeCategory(metadata.category);
+            const tags = normalizeTags(metadata.tags, category.label, allowMultipleTags);
             const excerpt = metadata.excerpt?.trim() || excerptFromContent(content);
             posts.push({
                 slug,
                 title: metadata.title.trim(),
                 excerpt,
                 category,
-                tags: metadata.tags ?? [],
+                tags,
                 author: config.getAuthor(metadata.author),
                 date: metadata.date,
                 dateLong: fmtLong.format(dateObj),
@@ -259,7 +271,121 @@ export function createBlog(config) {
         const featured = list.filter((p) => p.featured);
         return (featured[0] ?? list[0]);
     }
-    return { getAllPosts, getAllPostsFull, getPostBySlug, getCategories, pickHero };
+    async function getAllTags() {
+        const posts = await getAllPosts();
+        const map = new Map();
+        for (const post of posts) {
+            for (const tagName of post.tags) {
+                const tag = toBlogTag(tagName);
+                map.set(tag.slug, tag);
+            }
+        }
+        return Array.from(map.values()).sort((a, b) => a.name.localeCompare(b.name));
+    }
+    async function getPostsByTag(tagSlug) {
+        const posts = await getAllPosts();
+        return posts.filter((post) => post.tags.some((tagName) => slugify(tagName) === tagSlug));
+    }
+    async function getPostsByAuthor(authorId) {
+        const posts = await getAllPosts();
+        return posts.filter((post) => post.author.id === authorId);
+    }
+    async function getAllAuthors() {
+        const posts = await getAllPosts();
+        const map = new Map();
+        for (const post of posts)
+            map.set(post.author.id, post.author);
+        return Array.from(map.values()).sort((a, b) => a.name.localeCompare(b.name));
+    }
+    async function getAuthorSummaries() {
+        const posts = await getAllPosts();
+        const map = new Map();
+        for (const post of posts) {
+            const existing = map.get(post.author.id);
+            if (!existing) {
+                map.set(post.author.id, {
+                    author: post.author,
+                    postCount: 1,
+                    latestPostDate: post.date
+                });
+                continue;
+            }
+            existing.postCount += 1;
+            if (parseISODate(post.date).getTime() > parseISODate(existing.latestPostDate).getTime()) {
+                existing.latestPostDate = post.date;
+            }
+        }
+        return Array.from(map.values()).sort((a, b) => b.postCount - a.postCount || a.author.name.localeCompare(b.author.name));
+    }
+    async function getArchiveGroups() {
+        const posts = await getAllPosts();
+        const map = new Map();
+        for (const post of posts) {
+            const date = parseISODate(post.date);
+            const year = date.getUTCFullYear();
+            const month = date.getUTCMonth() + 1;
+            const key = `${year}-${String(month).padStart(2, '0')}`;
+            const existing = map.get(key);
+            if (existing) {
+                existing.posts.push(post);
+                existing.count += 1;
+                continue;
+            }
+            map.set(key, {
+                id: key,
+                year,
+                month,
+                label: fmtArchive.format(date),
+                count: 1,
+                posts: [post]
+            });
+        }
+        return Array.from(map.values()).sort((a, b) => b.id.localeCompare(a.id));
+    }
+    async function getAdjacentPosts(slug) {
+        const posts = await getAllPosts();
+        const index = posts.findIndex((post) => post.slug === slug);
+        if (index === -1)
+            return { previous: null, next: null };
+        return {
+            previous: posts[index + 1] ?? null,
+            next: posts[index - 1] ?? null
+        };
+    }
+    async function getRelatedPosts(slug, limit = 3) {
+        const posts = await getAllPosts();
+        const current = posts.find((post) => post.slug === slug);
+        if (!current)
+            return [];
+        const primaryTag = current.tags[0];
+        if (primaryTag) {
+            const primaryTagSlug = slugify(primaryTag);
+            const sameTag = posts
+                .filter((post) => post.slug !== slug && post.tags.some((tagName) => slugify(tagName) === primaryTagSlug))
+                .sort((a, b) => parseISODate(b.date).getTime() - parseISODate(a.date).getTime())
+                .slice(0, limit);
+            if (sameTag.length > 0)
+                return sameTag;
+        }
+        return posts
+            .filter((post) => post.slug !== slug && post.category.slug === current.category.slug)
+            .slice(0, limit);
+    }
+    return {
+        getAllPosts,
+        getAllPostsFull,
+        getPostBySlug,
+        getCategories,
+        pickHero,
+        getAllTags,
+        getPostsByTag,
+        getPostsByAuthor,
+        getAllAuthors,
+        getAuthorSummaries,
+        getArchiveGroups,
+        getAdjacentPosts,
+        getRelatedPosts
+    };
 }
 export function parseVivaBlogFrontmatter(data) {
     return vivaBlogFrontmatterSchema.parse(data);
@@ -316,6 +442,7 @@ function toBlogTag(name) {
 }
 export function createRawBlog(config) {
     const categoryOrder = config.categoryOrder ?? DEFAULT_CATEGORY_ORDER;
+    const allowMultipleTags = config.allowMultipleTags ?? false;
     const renderMarkdown = config.renderMarkdown ?? defaultRenderMarkdown;
     let cachedContentIndex = null;
     async function buildContentIndex() {
@@ -341,6 +468,7 @@ export function createRawBlog(config) {
             const dateObj = parseISODate(metadata.date);
             const rt = minutesToLabels(readingTime(content).minutes);
             const category = normalizeCategory(metadata.category);
+            const tags = normalizeTags(metadata.tags, category.label, allowMultipleTags);
             const excerpt = metadata.excerpt?.trim() || excerptFromContent(content);
             const rendered = await renderMarkdown(content);
             posts.push({
@@ -348,7 +476,7 @@ export function createRawBlog(config) {
                 title: metadata.title.trim(),
                 excerpt,
                 category,
-                tags: metadata.tags ?? [],
+                tags,
                 author: config.getAuthor(metadata.author),
                 authorId: metadata.author,
                 date: metadata.date,
@@ -443,17 +571,19 @@ export function createRawBlog(config) {
         const current = posts.find((post) => post.slug === slug);
         if (!current)
             return [];
-        const tagSet = new Set(current.tags.map((tag) => slugify(tag)));
+        const primaryTag = current.tags[0];
+        if (primaryTag) {
+            const primaryTagSlug = slugify(primaryTag);
+            const sameTag = posts
+                .filter((post) => post.slug !== slug && post.tags.some((tagName) => slugify(tagName) === primaryTagSlug))
+                .sort((a, b) => parseISODate(b.date).getTime() - parseISODate(a.date).getTime())
+                .slice(0, limit);
+            if (sameTag.length > 0)
+                return sameTag;
+        }
         return posts
-            .filter((post) => post.slug !== slug)
-            .map((post) => {
-            const overlap = post.tags.filter((tag) => tagSet.has(slugify(tag))).length;
-            return { post, overlap };
-        })
-            .filter((entry) => entry.overlap > 0)
-            .sort((a, b) => b.overlap - a.overlap)
-            .slice(0, limit)
-            .map((entry) => entry.post);
+            .filter((post) => post.slug !== slug && post.category.slug === current.category.slug)
+            .slice(0, limit);
     }
     return {
         getAllPosts,

package/packages/core/dist/server/docs.d.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+import type { DocsPage, DocsPageFull, DocsPageWithContent, DocsSidebarSection, DocsSection } from '../types/docs';
+declare const docsFrontmatterSchema: z.ZodObject<{
+    title: z.ZodString;
+    navTitle: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    section: z.ZodOptional<z.ZodString>;
+    sectionLabel: z.ZodOptional<z.ZodString>;
+    order: z.ZodOptional<z.ZodNumber>;
+    sectionOrder: z.ZodOptional<z.ZodNumber>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    updatedAt: z.ZodOptional<z.ZodString>;
+    draft: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type DocsFrontmatter = z.infer<typeof docsFrontmatterSchema>;
+export type DocsFrontmatterAdapter = (args: {
+    data: unknown;
+    content: string;
+    slug: string;
+    path: string;
+}) => DocsFrontmatter;
+type CompiledModule = {
+    default: DocsPageFull['component'];
+};
+export type DocsCreateConfig = {
+    compiledModules: Record<string, () => Promise<CompiledModule>>;
+    rawModules: Record<string, () => Promise<string>>;
+    defaultSectionLabel?: string;
+    sectionOrder?: string[];
+    mapFrontmatter?: DocsFrontmatterAdapter;
+};
+export type DocsMarkdownRenderer = (markdown: string) => string | Promise<string>;
+export type RawDocsCreateConfig = {
+    rawModules: Record<string, () => Promise<string>>;
+    defaultSectionLabel?: string;
+    sectionOrder?: string[];
+    mapFrontmatter?: DocsFrontmatterAdapter;
+    renderMarkdown?: DocsMarkdownRenderer;
+};
+export declare function createDocs(config: DocsCreateConfig): {
+    getAllPages: () => Promise<DocsPage[]>;
+    getAllPagesFull: () => Promise<DocsPageFull[]>;
+    getPageBySlug: (slug: string) => Promise<DocsPageFull | null>;
+    getSections: () => Promise<DocsSection[]>;
+    getSidebar: () => Promise<DocsSidebarSection[]>;
+    getAdjacentPages: (slug: string) => Promise<{
+        previous: DocsPage | null;
+        next: DocsPage | null;
+    }>;
+    pickLandingPage: () => Promise<DocsPage | null>;
+};
+export declare function createRawDocs(config: RawDocsCreateConfig): {
+    getAllPages: () => Promise<DocsPage[]>;
+    getAllPagesWithContent: () => Promise<DocsPageWithContent[]>;
+    getPageBySlug: (slug: string) => Promise<DocsPageWithContent | null>;
+    getSections: () => Promise<DocsSection[]>;
+    getSidebar: () => Promise<DocsSidebarSection[]>;
+    getAdjacentPages: (slug: string) => Promise<{
+        previous: DocsPage | null;
+        next: DocsPage | null;
+    }>;
+    pickLandingPage: () => Promise<DocsPage | null>;
+};
+export {};