astro-blog-kit 0.4.2 → 0.4.3

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.2",
+  "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 };
 }