astro-blog-kit 0.4.1 → 0.4.3

package/README.md

@@ -6,10 +6,10 @@ A ready-to-use blog system for Astro with WordPress headless support, optional i
 
 - 🚀 **One command setup** — `npx astro-blog-kit init`
 - 📝 **WordPress headless** — connects to WordPress REST API out of the box
-- 🎨 **Multiple layouts** — magazine, grid, and list
+- 🎨 **Multiple layouts** — magazine, featured, grid, cards
 - 💬 **Comment system** — with secure proxy to WordPress
 - 🌍 **Optional i18n** — multi-language support
-- 🎨 **Themeable** — customize colors and fonts via `blogKit()` config
+- 🎨 **Fully themeable** — colors, fonts, hero texts, and UI labels via `blog.config.ts`
 - 📦 **Zero config** — works without any configuration
 
 ---
@@ -47,20 +47,13 @@ And will automatically create:
 
 ```js
 // astro.config.mjs
-import { defineConfig } from "astro/config";
-import { blogKit } from "astro-blog-kit/integration";
+import { defineConfig } from 'astro/config';
+import { blogKit } from 'astro-blog-kit/integration';
+import config from './blog.config';
+import { toBlogKitConfig } from 'astro-blog-kit';
 
 export default defineConfig({
-  integrations: [
-    blogKit({
-      postsPerPage: 5,
-      defaultLayout: "magazine",
-      theme: {
-        accent: "#facc15",
-        fontHeading: "Georgia, serif",
-      },
-    }),
-  ],
+  integrations: [blogKit(toBlogKitConfig(config))],
 });
 ```
 
@@ -93,66 +86,157 @@ npm run dev
 ### `blog.config.ts`
 
 ```ts
-import { defineBlogConfig } from "astro-blog-kit";
+import { defineBlogConfig } from 'astro-blog-kit';
 
 export default defineBlogConfig({
-  wpUrl: "https://cms.yourdomain.com",
+  wpUrl: import.meta.env.WP_API_URL || 'https://cms.yourdomain.com',
   postsPerPage: 5,
-  defaultLayout: "magazine",
-  locale: "en",
+  defaultLayout: 'magazine', // 'magazine' | 'grid' | 'featured' | 'cards'
+  locale: 'en',              // 'en' | 'es'
+
   theme: {
-    accent: "#facc15",
-    background: "#ffffff",
-    text: "#0a0a0a",
-    fontHeading: "Georgia, serif",
-    fontBody: "system-ui, sans-serif",
+    accent:       '#facc15',
+    background:   '#ffffff',
+    surface:      '#f8f8f8',
+    text:         '#0a0a0a',
+    muted:        '#6b7280',
+    mutedLight:   '#9ca3af',
+    border:       '#e5e7eb',
+    black:        '#0a0a0a',
+    white:        '#ffffff',
+    fontHeading:  'Georgia, serif',
+    fontBody:     'system-ui, sans-serif',
+    fontMono:     'monospace',
+    fontDisplay:  'Georgia, serif',
+    containerMax: '1200px',
+  },
+
+  hero: {
+    tagline:     'Our Blog',
+    titleLine1:  'Latest',
+    titleLine2:  'Articles',
+    description: 'Welcome to our blog.',
+  },
+
+  ui: {
+    readMoreLabel:          'Read more →',
+    btnPrev:                'Previous',
+    btnNext:                'Next',
+    commentButtonColor:     'var(--bk-accent)',
+    commentButtonTextColor: 'var(--bk-black)',
+    paginationStyle:        'minimal', // 'minimal' | 'numbered'
+    // paginationBtnBg:         '#facc15',
+    // paginationBtnText:       '#0a0a0a',
+    // paginationBtnHoverBg:    '#0a0a0a',
+    // paginationBtnHoverText:  '#ffffff',
+    // paginationActiveBg:      '#facc15',
+    // paginationActiveText:    '#0a0a0a',
   },
 });
 ```
 
-### Theme options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `accent` | `string` | `#facc15` | Primary accent color |
-| `background` | `string` | `#ffffff` | Background color |
-| `surface` | `string` | `#f8f8f8` | Surface color (cards, sidebars) |
-| `text` | `string` | `#0a0a0a` | Primary text color |
-| `muted` | `string` | `#6b7280` | Secondary text color |
-| `border` | `string` | `#e5e7eb` | Border color |
-| `fontHeading` | `string` | `Georgia, serif` | Heading font |
-| `fontBody` | `string` | `system-ui, sans-serif` | Body font |
-| `fontMono` | `string` | `monospace` | Monospace font |
-| `containerMax` | `string` | `1200px` | Max container width |
+---
+
+### theme
+
+| Property       | Default                 | Description                         |
+| :------------- | :---------------------- | :---------------------------------- |
+| `accent`       | `#facc15`               | Primary accent color                |
+| `background`   | `#ffffff`               | Blog section background             |
+| `surface`      | `#f8f8f8`               | Cards and sidebar background        |
+| `text`         | `#0a0a0a`               | Primary text color                  |
+| `muted`        | `#6b7280`               | Secondary text color                |
+| `mutedLight`   | `#9ca3af`               | Subtle text color                   |
+| `border`       | `#e5e7eb`               | Border color                        |
+| `black`        | `#0a0a0a`               | Badge and title highlight           |
+| `white`        | `#ffffff`               | Text on dark backgrounds            |
+| `fontHeading`  | `Georgia, serif`        | Heading font                        |
+| `fontBody`     | `system-ui, sans-serif` | Body font                           |
+| `fontMono`     | `monospace`             | Monospace font                      |
+| `fontDisplay`  | `Georgia, serif`        | Display/hero font                   |
+| `containerMax` | `1200px`                | Max width of the blog container     |
 
 ---
 
-## Layouts
+### hero
+
+| Property      | Default                | Description                     |
+| :------------ | :--------------------- | :------------------------------ |
+| `tagline`     | `Our Blog`             | Badge text above the title      |
+| `titleLine1`  | `Latest`               | First line of the hero title    |
+| `titleLine2`  | `Articles`             | Second line (highlighted)       |
+| `description` | `Welcome to our blog.` | Paragraph below the title       |
 
-### Magazine (default)
-Featured post on the left + smaller posts on the right.
+---
 
-### Grid
-3-column card grid (responsive: 2 cols on tablet, 1 on mobile).
+### ui
+
+| Property                 | Default            | Description                        |
+| :----------------------- | :----------------- | :--------------------------------- |
+| `readMoreLabel`          | `Read more →`      | Read more button label             |
+| `btnPrev`                | `Previous`         | Previous page button label         |
+| `btnNext`                | `Next`             | Next page button label             |
+| `commentButtonColor`     | `var(--bk-accent)` | Comment submit button background   |
+| `commentButtonTextColor` | `var(--bk-black)`  | Comment submit button text color   |
+| `paginationStyle`        | `minimal`          | `minimal` or `numbered`            |
+| `paginationBtnBg`        | `accent`           | PREV/NEXT button background        |
+| `paginationBtnText`      | `black`            | PREV/NEXT button text color        |
+| `paginationBtnHoverBg`   | `text`             | PREV/NEXT button hover background  |
+| `paginationBtnHoverText` | `white`            | PREV/NEXT button hover text color  |
+| `paginationActiveBg`     | `accent`           | Active page number background      |
+| `paginationActiveText`   | `black`            | Active page number text color      |
 
-### List
-Horizontal rows with image on the left.
+---
 
-```astro
-<BlogList layout="grid" ... />
-<BlogList layout="list" ... />
-<BlogList layout="magazine" ... />
+## CSS Variables
+
+All theme values are available globally with the `--bk-` prefix:
+
+```css
+var(--bk-accent)
+var(--bk-background)
+var(--bk-surface)
+var(--bk-text)
+var(--bk-muted)
+var(--bk-muted-light)
+var(--bk-border)
+var(--bk-black)
+var(--bk-white)
+var(--bk-font-heading)
+var(--bk-font-body)
+var(--bk-font-mono)
+var(--bk-font-display)
+var(--bk-container-max)
+var(--bk-pagination-btn-bg)
+var(--bk-pagination-btn-text)
+var(--bk-pagination-btn-hover-bg)
+var(--bk-pagination-btn-hover-text)
+var(--bk-pagination-active-bg)
+var(--bk-pagination-active-text)
+var(--bk-comment-btn-bg)
+var(--bk-comment-btn-text)
 ```
 
 ---
 
+## Layouts
+
+| Layout      | Description                           |
+| :---------- | :------------------------------------ |
+| `magazine`  | Featured post + side grid             |
+| `grid`      | 3-column card grid                    |
+| `featured`  | Large hero image + grid below         |
+| `cards`     | Image background with text overlay    |
+
+---
+
 ## Components
 
 ### `<BlogList>`
 
 ```astro
 ---
-import { BlogList } from "astro-blog-kit/components";
+import { BlogList } from 'astro-blog-kit/components';
 ---
 <BlogList
   posts={posts}
@@ -161,7 +245,7 @@ import { BlogList } from "astro-blog-kit/components";
   basePath="/blog/page/"
   blogBase="/blog/"
   dateLocale="en-US"
-  t={t}
+  t={bt}
   locale="en"
   layout="magazine"
 />
@@ -171,7 +255,7 @@ import { BlogList } from "astro-blog-kit/components";
 
 ```astro
 ---
-import { BlogPost } from "astro-blog-kit/components";
+import { BlogPost } from 'astro-blog-kit/components';
 ---
 <BlogPost post={post} t={t} lang="en" />
 ```
@@ -180,7 +264,7 @@ import { BlogPost } from "astro-blog-kit/components";
 
 ```astro
 ---
-import { Comments } from "astro-blog-kit/components";
+import { Comments } from 'astro-blog-kit/components';
 ---
 <Comments comments={comments} postId={post.id ?? 0} />
 ```
@@ -189,7 +273,7 @@ import { Comments } from "astro-blog-kit/components";
 
 ```astro
 ---
-import { CommentForm } from "astro-blog-kit/components";
+import { CommentForm } from 'astro-blog-kit/components';
 ---
 <CommentForm postId={post.id ?? 0} apiRoute="/api/comments" />
 ```
@@ -201,30 +285,21 @@ import { CommentForm } from "astro-blog-kit/components";
 ### WordPress client
 
 ```ts
-import { createWPClient } from "astro-blog-kit/utils";
+import { createWPClient } from 'astro-blog-kit/utils';
 
-const wp = createWPClient("https://cms.yourdomain.com");
+const wp = createWPClient('https://cms.yourdomain.com');
 
-// Get paginated posts
 const { posts, total, totalPages } = await wp.getPosts({ perPage: 5, page: 1 });
-
-// Get all posts (for getStaticPaths)
 const posts = await wp.getAllPosts();
-
-// Get single post by slug
-const post = await wp.getPost("my-post-slug");
-
-// Get comments for a post
+const post = await wp.getPost('my-post-slug');
 const comments = await wp.getComments(postId);
-
-// Get categories
 const categories = await wp.getCategories();
 ```
 
 ### i18n helpers
 
 ```ts
-import { getLang, useTranslations, getBlogBase } from "astro-blog-kit/utils";
+import { getLang, useTranslations, getBlogBase } from 'astro-blog-kit/utils';
 
 const lang = getLang(Astro.url, import.meta.env.BASE_URL, config);
 const t = useTranslations(lang, { en, es });
@@ -234,12 +309,9 @@ const blogBase = getBlogBase(lang, import.meta.env.BASE_URL, config);
 ### Static paths helpers
 
 ```ts
-import { getStaticPathsForPosts, getStaticPathsForPages } from "astro-blog-kit/utils";
+import { getStaticPathsForPosts, getStaticPathsForPages } from 'astro-blog-kit/utils';
 
-// For [...slug].astro
 export const getStaticPaths = () => getStaticPathsForPosts(posts);
-
-// For [page].astro
 export const getStaticPaths = () => getStaticPathsForPages(posts, { postsPerPage: 5 });
 ```
 
@@ -251,19 +323,12 @@ Copy `node_modules/astro-blog-kit/examples/deploy-ftp.yml` to `.github/workflows
 
 Add these secrets to your GitHub repository (**Settings → Secrets**):
 
-| Secret | Description |
-|--------|-------------|
-| `FTP_HOST` | Your server hostname |
-| `FTP_USERNAME` | FTP username |
-| `FTP_PASSWORD` | FTP password |
-| `WP_API_URL` | Your WordPress URL |
-
-The workflow triggers on:
-- Push to `main`
-- WordPress webhook (`wp_update`, `wp_comment`)
-- Manual trigger
-
-To trigger from WordPress, install the **WP Webhooks** plugin and configure it to send a `repository_dispatch` event to GitHub when a post is published or a comment is approved.
+| Secret        | Description           |
+| :------------ | :-------------------- |
+| `FTP_HOST`    | Your server hostname  |
+| `FTP_USERNAME`| FTP username          |
+| `FTP_PASSWORD`| FTP password          |
+| `WP_API_URL`  | Your WordPress URL    |
 
 ---
 
@@ -273,8 +338,8 @@ To trigger from WordPress, install the **WP Webhooks** plugin and configure it t
 // astro.config.mjs
 blogKit({
   i18n: {
-    locales: ["en", "es"],
-    defaultLocale: "en",
+    locales: ['en', 'es'],
+    defaultLocale: 'en',
   },
 })
 ```
@@ -287,7 +352,7 @@ With i18n enabled:
 
 ## Requirements
 
-- Astro v4 or v5
+- Astro v4, v5, v6, or v7
 - Node.js 18+
 - WordPress with REST API enabled
 

package/define-config.ts

@@ -2,7 +2,16 @@
 // astro-blog-kit · define-config.ts
 // ─────────────────────────────────────────────────────────────
 
-import type { BlogKitConfig, BlogTheme, BlogHero, BlogUI } from "./types";
+import type {
+  BlogKitConfig,
+  BlogTheme,
+  BlogHero,
+  BlogHeroLocale,
+  BlogUI,
+  BlogUILocale,
+} from "./types";
+
+// ── Interfaces públicas ───────────────────────────────────────
 
 export interface BlogConfig {
   /** URL de tu WordPress. Ej: https://cms.tudominio.com */
@@ -26,132 +35,170 @@ export interface BlogConfig {
   };
 }
 
-/**
- * Define la configuración del blog con tipado completo.
- *
- * @example
- * ```ts
- * // blog.config.ts
- * import { defineBlogConfig } from 'astro-blog-kit';
- *
- * export default defineBlogConfig({
- *   wpUrl: 'https://cms.tudominio.com',
- *   postsPerPage: 5,
- *   defaultLayout: 'featured',
- *   locale: 'en',
- *   theme: {
- *     accent: '#facc15',
- *     background: '#0a1a0a',
- *     text: '#ffffff',
- *   },
- *   hero: {
- *     tagline: 'Technical Resources',
- *     titleLine1: 'Building',
- *     titleLine2: 'Insights',
- *     description: 'Practical knowledge for architects and engineers.',
- *   },
- *   ui: {
- *     readMoreLabel: 'Read more →',
- *     btnPrev: 'Previous',
- *     btnNext: 'Next',
- *     commentButtonColor: '#facc15',
- *     commentButtonTextColor: '#0a0a0a',
- *     paginationStyle: 'minimal',
- *   },
- * });
- * ```
- */
+// ── defineBlogConfig ──────────────────────────────────────────
+
 export function defineBlogConfig(config: BlogConfig): BlogConfig {
   return {
-    postsPerPage: 5,
+    postsPerPage:  5,
     defaultLayout: "magazine",
-    locale: "en",
+    locale:        "en",
     ...config,
   };
 }
 
-/**
- * Convierte BlogConfig a BlogKitConfig para usar en astro.config.mjs
- */
+// ── toBlogKitConfig ───────────────────────────────────────────
+
 export function toBlogKitConfig(config: BlogConfig): BlogKitConfig {
   return {
-    postsPerPage: config.postsPerPage,
+    postsPerPage:  config.postsPerPage,
     defaultLayout: config.defaultLayout,
-    theme: config.theme,
-    hero: config.hero,
-    ui: config.ui,
-    i18n: config.i18n,
+    theme:         config.theme,
+    hero:          config.hero,
+    ui:            config.ui,
+    i18n:          config.i18n,
   };
 }
 
-/**
- * Resuelve los textos del hero con fallbacks según el locale.
- * Usado internamente por BlogList.astro
- */
+// ── Helpers de detección de formato ──────────────────────────
+
+function isHeroI18n(hero: BlogHero): hero is Record<string, BlogHeroLocale> {
+  return typeof hero === "object" &&
+    Object.values(hero).some((v) => typeof v === "object" && v !== null);
+}
+
+function isUIi18n(ui: BlogUI): ui is Record<string, BlogUILocale> {
+  return typeof ui === "object" &&
+    Object.values(ui).some((v) => typeof v === "object" && v !== null);
+}
+
+// ── Defaults internos ─────────────────────────────────────────
+
+const HERO_DEFAULTS: Record<string, Required<BlogHeroLocale>> = {
+  en: {
+    tagline:     "Our Blog",
+    titleLine1:  "Latest",
+    titleLine2:  "Articles",
+    description: "Welcome to our blog.",
+  },
+  es: {
+    tagline:     "Nuestro Blog",
+    titleLine1:  "Últimos",
+    titleLine2:  "Artículos",
+    description: "Bienvenido a nuestro blog.",
+  },
+};
+
+const UI_DEFAULTS: Record<string, Required<BlogUILocale>> = {
+  en: {
+    readMoreLabel:          "Read more →",
+    btnPrev:                "Previous",
+    btnNext:                "Next",
+    commentButtonColor:     "var(--bk-accent)",
+    commentButtonTextColor: "var(--bk-black)",
+    paginationStyle:        "minimal",
+    paginationBtnBg:        "var(--bk-accent)",
+    paginationBtnText:      "var(--bk-black)",
+    paginationBtnHoverBg:   "var(--bk-text)",
+    paginationBtnHoverText: "var(--bk-white)",
+    paginationActiveBg:     "var(--bk-accent)",
+    paginationActiveText:   "var(--bk-black)",
+  },
+  es: {
+    readMoreLabel:          "Leer más →",
+    btnPrev:                "Anterior",
+    btnNext:                "Siguiente",
+    commentButtonColor:     "var(--bk-accent)",
+    commentButtonTextColor: "var(--bk-black)",
+    paginationStyle:        "minimal",
+    paginationBtnBg:        "var(--bk-accent)",
+    paginationBtnText:      "var(--bk-black)",
+    paginationBtnHoverBg:   "var(--bk-text)",
+    paginationBtnHoverText: "var(--bk-white)",
+    paginationActiveBg:     "var(--bk-accent)",
+    paginationActiveText:   "var(--bk-black)",
+  },
+};
+
+// ── resolveHero ───────────────────────────────────────────────
+
 export function resolveHero(
   hero: BlogHero | undefined,
   locale: string
-): Required<BlogHero> {
-  const defaults: Record<string, Required<BlogHero>> = {
-    en: {
-      tagline: "Our Blog",
-      titleLine1: "Latest",
-      titleLine2: "Articles",
-      description: "Welcome to our blog.",
-    },
-    es: {
-      tagline: "Nuestro Blog",
-      titleLine1: "Últimos",
-      titleLine2: "Artículos",
-      description: "Bienvenido a nuestro blog.",
-    },
-  };
+): Required<BlogHeroLocale> {
+  const d = HERO_DEFAULTS[locale] ?? HERO_DEFAULTS["en"];
 
-  const d = defaults[locale] ?? defaults["en"];
+  if (!hero) return d;
 
+  if (isHeroI18n(hero)) {
+    // Formato i18n: busca locale exacto → fallback 'en' → defaults internos
+    const src = hero[locale] ?? hero["en"] ?? {};
+    return {
+      tagline:     src.tagline     ?? d.tagline,
+      titleLine1:  src.titleLine1  ?? d.titleLine1,
+      titleLine2:  src.titleLine2  ?? d.titleLine2,
+      description: src.description ?? d.description,
+    };
+  }
+
+  // Formato plano legacy — backward compatible
+  const flat = hero as BlogHeroLocale;
   return {
-    tagline: hero?.tagline ?? d.tagline,
-    titleLine1: hero?.titleLine1 ?? d.titleLine1,
-    titleLine2: hero?.titleLine2 ?? d.titleLine2,
-    description: hero?.description ?? d.description,
+    tagline:     flat.tagline     ?? d.tagline,
+    titleLine1:  flat.titleLine1  ?? d.titleLine1,
+    titleLine2:  flat.titleLine2  ?? d.titleLine2,
+    description: flat.description ?? d.description,
   };
 }
 
-/**
- * Resuelve los labels de UI con fallbacks según el locale.
- * Usado internamente por BlogList.astro y Pagination.astro
- */
+// ── resolveUI ─────────────────────────────────────────────────
+
 export function resolveUI(
   ui: BlogUI | undefined,
   locale: string
-): Required<BlogUI> {
-  const defaults: Record<string, Required<BlogUI>> = {
-    en: {
-      readMoreLabel: "Read more →",
-      btnPrev: "Previous",
-      btnNext: "Next",
-      commentButtonColor: "var(--bk-accent)",
-      commentButtonTextColor: "var(--bk-black)",
-      paginationStyle: "minimal",
-    },
-    es: {
-      readMoreLabel: "Leer más →",
-      btnPrev: "Anterior",
-      btnNext: "Siguiente",
-      commentButtonColor: "var(--bk-accent)",
-      commentButtonTextColor: "var(--bk-black)",
-      paginationStyle: "minimal",
-    },
-  };
+): Required<BlogUILocale> {
+  const d = UI_DEFAULTS[locale] ?? UI_DEFAULTS["en"];
+
+  if (!ui) return d;
+
+  if (isUIi18n(ui)) {
+    // Campos visuales (colores) viven en cualquier locale; los buscamos
+    // en todos los locales disponibles para usarlos como fallback compartido.
+    const allLocales = Object.values(ui as Record<string, BlogUILocale>);
+    const visual = allLocales.find((v) => v.paginationBtnBg) ?? {};
+
+    const src = (ui as Record<string, BlogUILocale>)[locale] ??
+                (ui as Record<string, BlogUILocale>)["en"] ?? {};
 
-  const d = defaults[locale] ?? defaults["en"];
+    return {
+      readMoreLabel:          src.readMoreLabel          ?? d.readMoreLabel,
+      btnPrev:                src.btnPrev                ?? d.btnPrev,
+      btnNext:                src.btnNext                ?? d.btnNext,
+      commentButtonColor:     src.commentButtonColor     ?? visual.commentButtonColor     ?? d.commentButtonColor,
+      commentButtonTextColor: src.commentButtonTextColor ?? visual.commentButtonTextColor ?? d.commentButtonTextColor,
+      paginationStyle:        src.paginationStyle        ?? visual.paginationStyle        ?? d.paginationStyle,
+      paginationBtnBg:        src.paginationBtnBg        ?? visual.paginationBtnBg        ?? d.paginationBtnBg,
+      paginationBtnText:      src.paginationBtnText      ?? visual.paginationBtnText      ?? d.paginationBtnText,
+      paginationBtnHoverBg:   src.paginationBtnHoverBg   ?? visual.paginationBtnHoverBg   ?? d.paginationBtnHoverBg,
+      paginationBtnHoverText: src.paginationBtnHoverText ?? visual.paginationBtnHoverText ?? d.paginationBtnHoverText,
+      paginationActiveBg:     src.paginationActiveBg     ?? visual.paginationActiveBg     ?? d.paginationActiveBg,
+      paginationActiveText:   src.paginationActiveText   ?? visual.paginationActiveText   ?? d.paginationActiveText,
+    };
+  }
 
+  // Formato plano legacy — backward compatible
+  const flat = ui as BlogUILocale;
   return {
-    readMoreLabel: ui?.readMoreLabel ?? d.readMoreLabel,
-    btnPrev: ui?.btnPrev ?? d.btnPrev,
-    btnNext: ui?.btnNext ?? d.btnNext,
-    commentButtonColor: ui?.commentButtonColor ?? d.commentButtonColor,
-    commentButtonTextColor: ui?.commentButtonTextColor ?? d.commentButtonTextColor,
-    paginationStyle: ui?.paginationStyle ?? d.paginationStyle,
+    readMoreLabel:          flat.readMoreLabel          ?? d.readMoreLabel,
+    btnPrev:                flat.btnPrev                ?? d.btnPrev,
+    btnNext:                flat.btnNext                ?? d.btnNext,
+    commentButtonColor:     flat.commentButtonColor     ?? d.commentButtonColor,
+    commentButtonTextColor: flat.commentButtonTextColor ?? d.commentButtonTextColor,
+    paginationStyle:        flat.paginationStyle        ?? d.paginationStyle,
+    paginationBtnBg:        flat.paginationBtnBg        ?? d.paginationBtnBg,
+    paginationBtnText:      flat.paginationBtnText      ?? d.paginationBtnText,
+    paginationBtnHoverBg:   flat.paginationBtnHoverBg   ?? d.paginationBtnHoverBg,
+    paginationBtnHoverText: flat.paginationBtnHoverText ?? d.paginationBtnHoverText,
+    paginationActiveBg:     flat.paginationActiveBg     ?? d.paginationActiveBg,
+    paginationActiveText:   flat.paginationActiveText   ?? d.paginationActiveText,
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-blog-kit",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "A ready-to-use blog system for Astro with WordPress headless support, optional i18n, multiple layouts, and a comment system.",
   "type": "module",
   "license": "MIT",

package/templates/blog-config.ts.template

@@ -2,9 +2,9 @@ import { defineBlogConfig } from 'astro-blog-kit';
 
 export default defineBlogConfig({
   wpUrl: import.meta.env.WP_API_URL || '__WP_URL__',
-  postsPerPage: __POSTS_PER_PAGE__,
+  postsPerPage:  __POSTS_PER_PAGE__,
   defaultLayout: '__DEFAULT_LAYOUT__',
-  locale: '__LOCALE__',
+  locale:        '__LOCALE__',
 
   theme: {
     accent:       '#facc15',
@@ -23,28 +23,49 @@ export default defineBlogConfig({
     containerMax: '1200px',
   },
 
+  // ── Hero ──────────────────────────────────────────────────────
+  // Sitio i18n: un objeto por locale.
+  // Sitio monolingüe: puedes usar el formato plano:
+  //   hero: { tagline: 'Our Blog', titleLine1: 'Latest', ... }
   hero: {
-    tagline:     '__T_TAGLINE__',
-    titleLine1:  '__T_TITLE_LINE1__',
-    titleLine2:  '__T_TITLE_LINE2__',
-    description: '__T_DESCRIPTION__',
+    en: {
+      tagline:     'Our Blog',
+      titleLine1:  'Latest',
+      titleLine2:  'Articles',
+      description: 'Welcome to our blog.',
+    },
+    es: {
+      tagline:     'Nuestro Blog',
+      titleLine1:  'Últimos',
+      titleLine2:  'Artículos',
+      description: 'Bienvenido a nuestro blog.',
+    },
   },
 
+  // ── UI labels ────────────────────────────────────────────────
+  // Los labels de texto van por locale.
+  // Los campos visuales (colores, paginationStyle) son compartidos:
+  // ponlos en cualquier locale y aplican a todos.
   ui: {
-    readMoreLabel:          '__T_BTNCTA__',
-    btnPrev:                '__T_BTN_PREV__',
-    btnNext:                '__T_BTN_NEXT__',
-    commentButtonColor:     'var(--bk-accent)',
-    commentButtonTextColor: 'var(--bk-black)',
-    paginationStyle:        'minimal',
-    // ── Personalización de paginación (opcional) ──────────────
-    // Descomenta y cambia los valores según tu marca.
-    // Por defecto usan el accent y black del tema.
-    // paginationBtnBg:         '#facc15',  // fondo botón PREV/NEXT
-    // paginationBtnText:       '#0a0a0a',  // texto botón PREV/NEXT
-    // paginationBtnHoverBg:    '#0a0a0a',  // fondo hover
-    // paginationBtnHoverText:  '#ffffff',  // texto hover
-    // paginationActiveBg:      '#facc15',  // fondo página activa
-    // paginationActiveText:    '#0a0a0a',  // texto página activa
+    en: {
+      readMoreLabel: 'Read more →',
+      btnPrev:       'Previous',
+      btnNext:       'Next',
+      // ── Colores compartidos (van aquí una sola vez) ──────────
+      commentButtonColor:     'var(--bk-accent)',
+      commentButtonTextColor: 'var(--bk-black)',
+      paginationStyle:        'minimal',
+      // paginationBtnBg:         '#facc15',
+      // paginationBtnText:       '#0a0a0a',
+      // paginationBtnHoverBg:    '#0a0a0a',
+      // paginationBtnHoverText:  '#ffffff',
+      // paginationActiveBg:      '#facc15',
+      // paginationActiveText:    '#0a0a0a',
+    },
+    es: {
+      readMoreLabel: 'Leer más →',
+      btnPrev:       'Anterior',
+      btnNext:       'Siguiente',
+    },
   },
-});
+});

package/types.ts

@@ -29,109 +29,144 @@ export interface I18nConfig {
 
 export interface BlogTranslations {
   blog: {
-    tagline: string;
+    tagline:     string;
     title_line1: string;
     title_line2: string;
     description: string;
-    btncta: string;
-    btn_prev: string;
-    btn_next: string;
+    btncta:      string;
+    btn_prev:    string;
+    btn_next:    string;
   };
 }
 
 export interface PaginationProps {
   currentPage: number;
-  totalPages: number;
-  basePath: string;
-  blogBase: string;
-  t: BlogTranslations;
+  totalPages:  number;
+  basePath:    string;
+  blogBase:    string;
+  t:           BlogTranslations;
 }
 
 export interface BlogListProps {
-  posts: BlogPost[];
+  posts:       BlogPost[];
   currentPage: number;
-  totalPages: number;
-  basePath: string;
-  blogBase: string;
-  dateLocale: string;
-  t: BlogTranslations;
-  locale: string;
-  layout?: BlogListLayout;
+  totalPages:  number;
+  basePath:    string;
+  blogBase:    string;
+  dateLocale:  string;
+  t:           BlogTranslations;
+  locale:      string;
+  layout?:     BlogListLayout;
 }
 
 export interface BlogPostProps {
   post: BlogPost;
-  t: BlogTranslations;
+  t:    BlogTranslations;
   lang: string;
 }
 
+// ── Theme ─────────────────────────────────────────────────────
+
 export interface BlogTheme {
-  accent?: string;
-  background?: string;
-  surface?: string;
-  text?: string;
-  muted?: string;
-  mutedLight?: string;
-  border?: string;
-  black?: string;
-  white?: string;
-  fontHeading?: string;
-  fontBody?: string;
-  fontMono?: string;
-  fontDisplay?: string;
+  accent?:       string;
+  background?:   string;
+  surface?:      string;
+  text?:         string;
+  muted?:        string;
+  mutedLight?:   string;
+  border?:       string;
+  black?:        string;
+  white?:        string;
+  fontHeading?:  string;
+  fontBody?:     string;
+  fontMono?:     string;
+  fontDisplay?:  string;
   containerMax?: string;
 }
 
-export interface BlogHero {
-  tagline?: string;
-  titleLine1?: string;
-  titleLine2?: string;
+// ── Hero ──────────────────────────────────────────────────────
+
+/** Textos del hero para un único locale */
+export interface BlogHeroLocale {
+  tagline?:     string;
+  titleLine1?:  string;
+  titleLine2?:  string;
   description?: string;
 }
 
-export interface BlogUI {
+/**
+ * Acepta dos formatos:
+ * - Plano (sitio monolingüe):  { tagline: 'Our Blog', ... }
+ * - Por locale (sitio i18n):   { en: { tagline: 'Our Blog' }, es: { tagline: 'Nuestro Blog' } }
+ */
+export type BlogHero = BlogHeroLocale | Record<string, BlogHeroLocale>;
+
+// ── UI ────────────────────────────────────────────────────────
+
+/** Labels y colores de UI para un único locale */
+export interface BlogUILocale {
   /** Texto del botón "leer más". @default "Read more →" */
-  readMoreLabel?: string;
+  readMoreLabel?:          string;
   /** Texto del botón de página anterior. @default "Previous" */
-  btnPrev?: string;
+  btnPrev?:                string;
   /** Texto del botón de página siguiente. @default "Next" */
-  btnNext?: string;
+  btnNext?:                string;
   /** Color de fondo del botón de comentarios. @default var(--bk-accent) */
-  commentButtonColor?: string;
+  commentButtonColor?:     string;
   /** Color del texto del botón de comentarios. @default var(--bk-black) */
   commentButtonTextColor?: string;
   /** Estilo de paginación. @default "minimal" */
-  paginationStyle?: "minimal" | "numbered";
-  /** Fondo botones PREV/NEXT. @default accent */
-  paginationBtnBg?: string;
-  /** Texto botones PREV/NEXT. @default black */
-  paginationBtnText?: string;
-  /** Fondo botones PREV/NEXT en hover. @default text */
-  paginationBtnHoverBg?: string;
-  /** Texto botones PREV/NEXT en hover. @default white */
+  paginationStyle?:        "minimal" | "numbered";
+  /** Fondo botones PREV/NEXT. @default var(--bk-accent) */
+  paginationBtnBg?:        string;
+  /** Texto botones PREV/NEXT. @default var(--bk-black) */
+  paginationBtnText?:      string;
+  /** Fondo botones PREV/NEXT en hover. @default var(--bk-text) */
+  paginationBtnHoverBg?:   string;
+  /** Texto botones PREV/NEXT en hover. @default var(--bk-white) */
   paginationBtnHoverText?: string;
-  /** Fondo página activa. @default accent */
-  paginationActiveBg?: string;
-  /** Texto página activa. @default black */
-  paginationActiveText?: string;
+  /** Fondo página activa. @default var(--bk-accent) */
+  paginationActiveBg?:     string;
+  /** Texto página activa. @default var(--bk-black) */
+  paginationActiveText?:   string;
 }
 
+/**
+ * Acepta dos formatos:
+ * - Plano (sitio monolingüe):  { readMoreLabel: 'Read more', ... }
+ * - Por locale (sitio i18n):   { en: { readMoreLabel: 'Read more' }, es: { readMoreLabel: 'Leer más' } }
+ *
+ * Nota: los campos visuales (colores, paginationStyle) son compartidos entre locales.
+ * Ponlos en cualquier locale (ej. `en`) — el resolver los tomará como fallback global.
+ */
+export type BlogUI = BlogUILocale | Record<string, BlogUILocale>;
+
+// ── Alias para backward compat ────────────────────────────────
+/** @deprecated Usa BlogHeroLocale */
+export type { BlogHeroLocale as BlogHeroFlat };
+/** @deprecated Usa BlogUILocale */
+export type { BlogUILocale as BlogUIFlat };
+
+// ── BlogKitConfig (integration.ts) ───────────────────────────
+
 export interface BlogKitConfig {
-  postsPerPage?: number;
-  i18n?: I18nConfig;
-  defaultLayout?: BlogListLayout;
+  postsPerPage?:   number;
+  i18n?:           I18nConfig;
+  defaultLayout?:  BlogListLayout;
   collectionName?: string;
-  theme?: BlogTheme;
-  hero?: BlogHero;
-  ui?: BlogUI;
+  theme?:          BlogTheme;
+  hero?:           BlogHero;
+  ui?:             BlogUI;
 }
 
+// ── Static paths ──────────────────────────────────────────────
+
 export interface PageStaticPath {
   params: { page: string };
-  props: { posts: BlogPost[]; currentPage: number; totalPages: number };
+  props:  { posts: BlogPost[]; currentPage: number; totalPages: number };
 }
 
 export interface PostStaticPath {
   params: { slug: string };
-  props: { post: BlogPost };
+  props:  { post: BlogPost };
 }