@hkdigital/lib-core 0.5.96 → 0.5.97

package/README.md

@@ -204,72 +204,24 @@ This library includes a complete design system with Tailwind CSS integration. Ba
    import heroResponsive from '$lib/assets/hero.jpg?preset=photo&responsive';
    ```
 
-6. **Meta setup** - Configure SEO, PWA, and favicons:
+6. **Meta setup (optional)** - SEO, PWA, and favicons:
 
    The library includes templates for PWA configuration, SEO metadata,
    favicon generation, manifest.json, sitemap.xml, and robots.txt.
 
-   **Copy template files to your project:**
+   **Quick setup:**
    ```bash
-   # Copy configuration and assets to src/lib/
+   # Copy template files to your project
    cp -r node_modules/@hkdigital/lib-core/meta/templates/lib/* src/lib/
-
-   # Copy route endpoints to src/routes/
    cp -r node_modules/@hkdigital/lib-core/meta/templates/routes/* src/routes/
    ```
 
-   **Customize for your app:**
-   - Replace images in `src/lib/assets/meta/` with your own:
-     - `favicon.png` (512×512px)
-     - `preview-landscape.png` (1200×630px for social media)
-     - `preview-square.png` (1200×1200px for social media)
-   - Edit `src/lib/config/meta.js`:
-     ```javascript
-     export const name = 'Your App Name';
-     export const shortName = 'App';
-     export const description = 'Your app description';
-     export const backgroundAndThemeColor = '#082962';
-
-     // Add your site routes for sitemap
-     export const siteRoutes = ['/', '/about', '/contact'];
-
-     // Configure robots.txt
-     export const robotsConfig = {
-       allowedHosts: '*',  // '*' allows all hosts
-       disallowedPaths: [],
-       allowAiTraining: true,
-       allowAiReading: true
-     };
-     ```
-
-   **Integrate into root layout:**
-   ```svelte
-   <!-- src/routes/+layout.svelte -->
-   <script>
-     import { Favicons, PWA, SEO, config } from '$lib/meta.js';
-
-     let { children, data } = $props();
-   </script>
-
-   <Favicons {config} />
-   <PWA {config} />
-   <SEO {config} locale={data?.locale} />
-
-   {@render children()}
-   ```
+   Then customize `$lib/meta/config.js` and replace placeholder images
+   in `$lib/meta/` with your own.
 
-   **What you get:**
-   - Automatic favicon generation (16, 32, 192, 512px)
-   - Apple touch icons (120, 152, 167, 180px)
-   - SEO meta tags and Open Graph support
-   - Social media preview images
-   - Multi-language support with auto-detection
-   - Dynamic `/manifest.json` endpoint
-   - Dynamic `/sitemap.xml` endpoint
-   - Dynamic `/robots.txt` with AI bot control
-
-   See the [meta template README](./src/lib/meta/templates/README.md) for
-   complete documentation.
+   **For complete setup instructions and documentation**, see:
+   - [Meta setup guide](./src/lib/meta/templates/README.md)
+   - [Meta utilities API](./src/lib/meta/README.md)
 
 ### Logging System
 

package/dist/config/generators/imagetools.d.ts

@@ -8,10 +8,10 @@
  * @param {number[]} [options.faviconSizes=FAVICON_SIZES]
  * @param {number[]} [options.appleTouchSizes=APPLE_TOUCH_SIZES]
  *
- * @param {{width: number, height: number}} [options.seoLandscapeSize]
+ * @param {[number,number][]} [options.seoLandscapeSizes]
  *   SEO landscape image size
  *
- * @param {{width: number, height: number}} [options.seoSquareSize]
+ * @param {[number,number][]} [options.seoSquareSizes]
  *   SEO square image size
  *
  * @returns {(
@@ -23,14 +23,8 @@ export function generateResponseConfigs(options?: {
     thumbnailWidth?: number | undefined;
     faviconSizes?: number[] | undefined;
     appleTouchSizes?: number[] | undefined;
-    seoLandscapeSize?: {
-        width: number;
-        height: number;
-    } | undefined;
-    seoSquareSize?: {
-        width: number;
-        height: number;
-    } | undefined;
+    seoLandscapeSizes?: [number, number][] | undefined;
+    seoSquareSizes?: [number, number][] | undefined;
 }): (entries: [string, string[]][]) => (Record<string, string | string[]>[]);
 /**
  * Configures and returns a function that can be used as

package/dist/config/generators/imagetools.js

@@ -21,8 +21,15 @@ const APPLE_TOUCH_SIZES = [
   180  // iPhone retina, iOS home screen
 ];
 
-const SEO_LANDSCAPE_SIZE = { width: 1200, height: 630 };
-const SEO_SQUARE_SIZE = { width: 1200, height: 1200 };
+const SEO_LANDSCAPE_SIZES =
+	[
+		[1200, 630]
+	];
+
+const SEO_SQUARE_SIZES =
+	[
+		[1200,1200]
+	];
 
 const DEFAULT_PRESETS = {
 	default: {
@@ -73,10 +80,10 @@ const DEFAULT_PRESETS = {
  * @param {number[]} [options.faviconSizes=FAVICON_SIZES]
  * @param {number[]} [options.appleTouchSizes=APPLE_TOUCH_SIZES]
  *
- * @param {{width: number, height: number}} [options.seoLandscapeSize]
+ * @param {[number,number][]} [options.seoLandscapeSizes]
  *   SEO landscape image size
  *
- * @param {{width: number, height: number}} [options.seoSquareSize]
+ * @param {[number,number][]} [options.seoSquareSizes]
  *   SEO square image size
  *
  * @returns {(
@@ -135,8 +142,8 @@ export function generateResponseConfigs(options) {
 		const widths = options?.widths ?? DEFAULT_WIDTHS;
 		const faviconSizes = options?.faviconSizes ?? FAVICON_SIZES;
 		const appleTouchSizes = options?.appleTouchSizes ?? APPLE_TOUCH_SIZES;
-		const seoLandscapeSize = options?.seoLandscapeSize ?? SEO_LANDSCAPE_SIZE;
-		const seoSquareSize = options?.seoSquareSize ?? SEO_SQUARE_SIZE;
+		const seoLandscapeSizes = options?.seoLandscapeSizes ?? SEO_LANDSCAPE_SIZES;
+		const seoSquareSizes = options?.seoSquareSizes ?? SEO_SQUARE_SIZES;
 
 		delete configPairs.responsive;
 		delete configPairs.favicons;
@@ -185,25 +192,35 @@ export function generateResponseConfigs(options) {
 		// Handle seo-landscape directive - generate landscape SEO image
 
 		if (isSeoLandscape) {
-			return [{
-				...configPairs,
-				w: String(seoLandscapeSize.width),
-				h: String(seoLandscapeSize.height),
-				format: 'jpg',
-				quality: '95'
-			}];
+			const seoLandscapeConfigs = seoLandscapeSizes.map(([w, h]) => {
+				return {
+					...configPairs,
+					w: String(w),
+					h: String(h),
+					format: 'jpg',
+					quality: '95'
+				};
+			});
+			// console.log('**** Returning seo-landscape configs:', seoLandscapeConfigs);
+			// @note return two elements, otherwise imagetools collapses the array
+			return [...seoLandscapeConfigs, thumbnailConfig];
 		}
 
 		// Handle seo-square directive - generate square SEO image
 
 		if (isSeoSquare) {
-			return [{
-				...configPairs,
-				w: String(seoSquareSize.width),
-				h: String(seoSquareSize.height),
-				format: 'jpg',
-				quality: '95'
-			}];
+			const seoSquareConfigs = seoSquareSizes.map(([w,h]) => {
+				return {
+					...configPairs,
+					w: String(w),
+					h: String(h),
+					format: 'jpg',
+					quality: '95'
+				};
+			});
+			// console.log('**** Returning seo-square configs:', seoSquareConfigs);
+			// @note return two elements, otherwise imagetools collapses the array
+			return [...seoSquareConfigs, thumbnailConfig];
 		}
 
 		if (!responsiveConfig) {
@@ -217,6 +234,7 @@ export function generateResponseConfigs(options) {
 		const responsiveConfigs = widths.map((w) => {
 			return { ...configPairs, w: String(w) };
 		});
+
 		const result = [...responsiveConfigs, thumbnailConfig];
 		// console.log('Returning responsive + thumbnail configs:', result);
 		return result;
@@ -247,7 +265,7 @@ export function generateDefaultDirectives(options) {
 
 		let presetName = params.get('preset');
 
-		// > Return metadata if directive 'responsive' is set
+		// > Responsive image support: return meta data instead of image data
 
 		// @see https://github.com/JonasKruckenberg/
 		//      imagetools/blob/main/docs/directives.md#metadata
@@ -270,16 +288,16 @@ export function generateDefaultDirectives(options) {
 			params.set('as', 'metadata');
 		}
 
-		// > Return picture (URL) if directive 'seo-landscape' is set
+		// > Return metadata if directive 'seo-landscape' is set
 
 		if (params.has('seo-landscape')) {
-			params.set('as', 'picture');
+			params.set('as', 'metadata');
 		}
 
-		// > Return picture (URL) if directive 'seo-square' is set
+		// > Return metadata if directive 'seo-square' is set
 
 		if (params.has('seo-square')) {
-			params.set('as', 'picture');
+			params.set('as', 'metadata');
 		}
 
 		// > Process presets

package/dist/config/imagetools.d.ts

@@ -87,12 +87,12 @@ declare module '*?apple-touch-icons' {
 
 // Generate SEO landscape image (1200x630)
 declare module '*?seo-landscape' {
-  const out: string;
+  const out: ImageSource;
   export default out;
 }
 
 // Generate SEO square image (1200x1200)
 declare module '*?seo-square' {
-  const out: string;
+  const out: ImageSource;
   export default out;
 }

package/dist/meta/components/Favicons.svelte

@@ -10,7 +10,7 @@
   /** @type {{ config: MetaConfig }} */
   let { config } = $props();
 
-  const { faviconImages, appleTouchIcons } = config;
+  let { faviconImages, appleTouchIcons } = $derived(config);
 </script>
 
 <svelte:head>

package/dist/meta/components/Favicons.svelte.d.ts

@@ -4,7 +4,7 @@ type Favicons = {
     $set?(props: Partial<$$ComponentProps>): void;
 };
 declare const Favicons: import("svelte").Component<{
-    config: import("../config.typedef.js").MetaConfig;
+    config: import("../typedef.js").MetaConfig;
 }, {}, "">;
 type $$ComponentProps = {
     config: {
@@ -66,15 +66,19 @@ type $$ComponentProps = {
          */
         disablePageZoom: boolean;
         /**
-         * - Landscape SEO image URL (1200×630)
+         * Landscape SEO image URL (1200×630)
          */
-        SeoImageLandscape?: string | undefined;
+        previewImageLandscape?: import("../../config/typedef.js").ImageSource | undefined;
         /**
-         * - Square SEO image URL (1200×1200)
+         * Square SEO image URL (1200×1200)
+         */
+        previewImageSquare?: import("../../config/typedef.js").ImageSource | undefined;
+        /**
+         * - Alt text for social media image
          *
          * Favicon images (processed by imagetools)
          */
-        SeoImageSquare?: string | undefined;
+        previewImageAltText?: string | undefined;
         /**
          *   Processed favicon images
          */

package/dist/meta/components/PWA.svelte

@@ -12,8 +12,8 @@
   /** @type {{ config: MetaConfig }} */
   let { config } = $props();
 
-  const { themeColor, statusBarStyle, name, shortName, disablePageZoom } =
-    config;
+  let { themeColor, statusBarStyle, name, shortName, disablePageZoom } =
+    $derived(config);
 
   let shouldSetTitle = $state(false);
 

package/dist/meta/components/PWA.svelte.d.ts

@@ -4,7 +4,7 @@ type PWA = {
     $set?(props: Partial<$$ComponentProps>): void;
 };
 declare const PWA: import("svelte").Component<{
-    config: import("../config.typedef.js").MetaConfig;
+    config: import("../typedef.js").MetaConfig;
 }, {}, "">;
 type $$ComponentProps = {
     config: {
@@ -66,15 +66,19 @@ type $$ComponentProps = {
          */
         disablePageZoom: boolean;
         /**
-         * - Landscape SEO image URL (1200×630)
+         * Landscape SEO image URL (1200×630)
          */
-        SeoImageLandscape?: string | undefined;
+        previewImageLandscape?: import("../../config/typedef.js").ImageSource | undefined;
         /**
-         * - Square SEO image URL (1200×1200)
+         * Square SEO image URL (1200×1200)
+         */
+        previewImageSquare?: import("../../config/typedef.js").ImageSource | undefined;
+        /**
+         * - Alt text for social media image
          *
          * Favicon images (processed by imagetools)
          */
-        SeoImageSquare?: string | undefined;
+        previewImageAltText?: string | undefined;
         /**
          *   Processed favicon images
          */

package/dist/meta/components/SEO.svelte

@@ -11,25 +11,35 @@
    * SEO component props
    *
    * @typedef {Object} SEOProps
+   *
    * @property {MetaConfig} config - Configuration object
+   *
    * @property {string} [title] - Page title (defaults to config name)
+   *
    * @property {string} [description]
    *   Page description (defaults to config description)
-   * @property {string} [url] - Canonical URL for this page
-   * @property {string} [image]
-   *   Social media preview image URL (defaults to landscape SEO image)
-   * @property {string} [imageAlt] - Alt text for social media image
+   *
+   * @property {string} [canonicalUrl]
+   *   Canonical URL for this content to prevent duplicate content penalties
+   *
+   * @property {import('../../config/typedef.js').ImageSource}
+   *   [previewImageLandscape] - Landscape preview image (1200×630)
+   *
+   * @property {import('../../config/typedef.js').ImageSource}
+   *   [previewImageSquare] - Square preview image (1200×1200)
+   *
+   * @property {string} [previewImageAltText] - Alt text for preview images
+   *
    * @property {string} [type] - Open Graph type (default: 'website')
-   * @property {string} [locale]
-   *   Content locale (auto-detected from URL or defaults to config)
-   * @property {string} [siteName]
-   *   Site name for Open Graph (defaults to config name)
+   *
+   * @property {string} [locale] - Content locale (defaults to config locale)
+   *
    * @property {Record<string, string>} [alternateUrls]
    *   Alternate language URLs for hreflang tags
-   * @property {string} [robots]
-   *   Robots meta directives (e.g., 'noindex, nofollow')
-   * @property {boolean} [noAiTraining]
-   *   Prevent AI training on this page content
+   *
+   * @property {string} [robots] - Robots meta directives
+   *
+   * @property {boolean} [noAiTraining] - Block AI training on this page
    */
 
   /** @type {SEOProps} */
@@ -37,110 +47,136 @@
     config,
     title,
     description,
-    url = undefined,
-    image,
-    imageAlt,
+    canonicalUrl = undefined,
+
+    previewImageLandscape,
+    previewImageSquare,
+    previewImageAltText,
+
     type = 'website',
     locale = undefined,
-    siteName,
     alternateUrls = undefined,
     robots = undefined,
     noAiTraining = false
   } = $props();
 
   // Extract config values
-  const {
-    name: defaultTitle,
-    description: defaultDescription,
-    SeoImageLandscape,
-    SeoImageSquare,
-    defaultLocale,
-    languages
-  } = config;
-
-  // Use the landscape image as default (best for most platforms)
-  const defaultSeoImage = SeoImageLandscape || undefined;
-
-  // Apply defaults from config
-  title = title ?? defaultTitle;
-  description = description ?? defaultDescription;
-  image = image ?? defaultSeoImage;
-  imageAlt = imageAlt ?? title;
-  siteName = siteName ?? defaultTitle;
-
-  // Use locale from prop or fall back to config default
-  const finalLocale = locale || defaultLocale;
+  let defaultLocale = $derived(config.defaultLocale);
+  let languages = $derived(config.languages);
+
+  /**
+   * Get first image source from imageSource array
+   *
+   * @param {ImageSource|undefined|null} imageSource
+   *
+   * @returns {string|null} image source url
+   *
+   * @throws {Error} invalid parameter
+   */
+  function imageSourceToSrc( imageSource ) {
+    if( !imageSource ) {
+      return null;
+    }
+
+    if( !Array.isArray( imageSource ) || !imageSource[0] || !imageSource[0].src ) {
+      throw new Error('Invalid [imageSource]');
+    }
+
+    return imageSource[0].src ?? null;
+  }
+
+  let imageLandscape = $derived.by( () => {
+    let image = previewImageLandscape ?? config.previewImageLandscape;
+
+    // console.log("image", image);
+
+    return imageSourceToSrc(image);
+  } );
+
+  // console.log("imageLandscape", imageLandscape);
+
+  let imageSquare = $derived.by( () => {
+    let image = previewImageSquare ?? config.previewImageSquare;
+
+    return imageSourceToSrc(image);
+  } );
+
+  let imageAltText = $derived(previewImageAltText ?? config.name);
+
+  let pageTitle = $derived(title ?? config.name);
+  let pageDescription = $derived(description ?? config.description);
+
+  let currentLocale = $derived(locale ?? defaultLocale);
 </script>
 
 <svelte:head>
-  <!-- Page title (overrides %title% from app.html) -->
-  <title>{title}</title>
+  <!-- Basic SEO: Page title (overrides %title% from app.html) -->
+  <title>{pageTitle}</title>
 
-  <!-- Basic SEO -->
-  <meta name="description" content={description}>
+  <!-- Basic SEO: Page title (overrides %title% from app.html) -->
+  {#if pageDescription}
+    <meta name="description" content={pageDescription} />
+  {/if}
+
+  {#if canonicalUrl}
+    <link rel="canonical" href={canonicalUrl} />
+    <meta property="og:url" content={canonicalUrl} />
+  {/if}
 
   <!-- Robots directives -->
   {#if robots}
-    <meta name="robots" content={robots}>
+    <meta name="robots" content={robots} />
   {/if}
 
   <!-- AI training and reading restrictions -->
   {#if noAiTraining}
     <!-- Google AI -->
-    <meta name="google-extended" content="noindex, nofollow">
+    <meta name="google-extended" content="noindex, nofollow" />
     <!-- OpenAI (ChatGPT) -->
-    <meta name="OAI-SearchBot" content="noindex, nofollow">
+    <meta name="OAI-SearchBot" content="noindex, nofollow" />
     <!-- Common Crawl -->
-    <meta name="CCBot" content="noindex, nofollow">
+    <meta name="CCBot" content="noindex, nofollow" />
     <!-- Anthropic Claude -->
-    <meta name="anthropic-ai" content="noindex, nofollow">
+    <meta name="anthropic-ai" content="noindex, nofollow" />
     <!-- General AI crawlers -->
-    <meta name="robots" content="noai, noimageai">
+    <meta name="robots" content="noai, noimageai" />
   {/if}
 
   <!-- Open Graph / Facebook / LinkedIn / Discord -->
-  <meta property="og:type" content={type}>
-  <meta property="og:title" content={title}>
-  <meta property="og:description" content={description}>
-  <meta property="og:site_name" content={siteName}>
-  <meta property="og:locale" content={finalLocale}>
-
-  {#if url}
-    <meta property="og:url" content={url}>
-    <link rel="canonical" href={url}>
+  <meta property="og:type" content={type} />
+  <meta property="og:site_name" content={config.name} />
+  <meta property="og:title" content={pageTitle} />
+  <meta property="og:description" content={pageDescription} />
+  <meta property="og:locale" content={currentLocale} />
+
+  <!-- Default seo/social image (landscape) -->
+  {#if imageLandscape}
+    <meta property="og:image" content={imageLandscape} />
+    <meta property="og:image:alt" content={imageAltText} />
+    <meta property="og:image:width" content="1200" />
+    <meta property="og:image:height" content="630" />
+    <meta property="og:image:type" content="image/jpeg" />
   {/if}
 
-  {#if image}
-    <meta property="og:image" content={image}>
-    <meta property="og:image:alt" content={imageAlt}>
-    <!-- Image metadata (dimensions from preprocessor) -->
-    {#if image === SeoImageLandscape}
-      <meta property="og:image:width" content="1200">
-      <meta property="og:image:height" content="630">
-      <meta property="og:image:type" content="image/jpeg">
-    {/if}
-  {/if}
-
-  <!-- Additional square image for platforms that prefer it -->
-  {#if SeoImageSquare && SeoImageSquare !== image}
-    <meta property="og:image" content={SeoImageSquare}>
-    <meta property="og:image:width" content="1200">
-    <meta property="og:image:height" content="1200">
-    <meta property="og:image:type" content="image/jpeg">
+  <!-- Additional image for platforms that prefer square images -->
+  {#if imageSquare}
+    <meta property="og:image" content={imageSquare} />
+    <meta property="og:image:width" content="1200" />
+    <meta property="og:image:height" content="1200" />
+    <meta property="og:image:type" content="image/jpeg" />
   {/if}
 
   <!-- Alternate locales for Open Graph -->
   {#each Object.entries(languages) as [code, config]}
-    {#if config.locale !== finalLocale}
-      <meta property="og:locale:alternate" content={config.locale}>
+    {#if config.locale !== currentLocale}
+      <meta property="og:locale:alternate" content={config.locale} />
     {/if}
   {/each}
 
   <!-- Alternate language URLs (hreflang) -->
   {#if alternateUrls}
     {#each Object.entries(alternateUrls) as [lang, href]}
-      <link rel="alternate" hreflang={lang} href={href}>
+      <link rel="alternate" hreflang={lang} {href} />
     {/each}
   {/if}
-
 </svelte:head>