@hkdigital/lib-core 0.5.11 → 0.5.13

package/README.md

@@ -32,6 +32,9 @@ pnpm add @skeletonlabs/skeleton
 # UI icons
 pnpm add @steeze-ui/heroicons
 
+# CSS processing (Tailwind and PostCSS)
+pnpm add tailwindcss @tailwindcss/postcss postcss autoprefixer
+
 # Logging
 pnpm add pino pino-pretty
 
@@ -42,13 +45,13 @@ pnpm add jsonwebtoken
 pnpm add @eslint/js eslint-plugin-import
 
 # Image processing
-pnpm add vite-imagetools
+pnpm add -D vite-imagetools
 ```
 
 **For other libraries**, install as dev dependencies and declare as peer dependencies:
 ```bash
 # Install as dev dependencies and peer dependencies
-pnpm add -D --save-peer @sveltejs/kit svelte svelte-preprocess runed valibot @skeletonlabs/skeleton @steeze-ui/heroicons pino pino-pretty jsonwebtoken @eslint/js eslint-plugin-import vite-imagetools
+pnpm add -D --save-peer @sveltejs/kit svelte svelte-preprocess runed valibot @skeletonlabs/skeleton @steeze-ui/heroicons tailwindcss @tailwindcss/postcss postcss autoprefixer pino pino-pretty jsonwebtoken @eslint/js eslint-plugin-import vite-imagetools
 ```
 
 ### Design System & Configuration
@@ -135,7 +138,8 @@ This library includes a complete design system with Tailwind CSS integration. Ba
    export default config;
    ```
 
-5. **TypeScript support for imagetools** - Add image import definitions to `app.d.ts`:
+5. **Image import type definitions** - Add imagetools type support to
+   `app.d.ts`:
    ```typescript
    // src/app.d.ts
    import '@hkdigital/lib-core/config/imagetools.d.ts';
@@ -179,6 +183,59 @@ This library includes a complete design system with Tailwind CSS integration. Ba
    import heroResponsive from '$lib/assets/hero.jpg?preset=photo&responsive';
    ```
 
+6. **(meta) folder setup** - Copy and configure PWA/favicon generation:
+
+   The library includes a complete `(meta)` folder with PWA configuration,
+   favicon generation, manifest.json, sitemap.xml, and robots.txt endpoints.
+
+   **Copy the folder to your project:**
+   ```bash
+   cp -r node_modules/@hkdigital/lib-core/src/routes/\(meta\) src/routes/
+   ```
+
+   **Customize for your app:**
+   - Replace `src/routes/(meta)/favicon.png` with your 512×512px image
+   - Edit `src/routes/(meta)/config.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 (prevent test sites from being indexed)
+     export const robotsConfig = {
+       allowedHosts: ['mysite.com', 'www.mysite.com'],
+       disallowedPaths: ['/admin/*'],
+       includeSitemap: true
+     };
+     ```
+
+   **Integrate into root layout:**
+   ```svelte
+   <!-- src/routes/+layout.svelte -->
+   <script>
+     import { Favicons, PWA } from './(meta)/index.js';
+   </script>
+
+   <Favicons />
+   <PWA />
+
+   {@render children()}
+   ```
+
+   **What you get:**
+   - Automatic favicon generation (16, 32, 192, 512px)
+   - Apple touch icons (120, 152, 167, 180px)
+   - Dynamic `/manifest.json` endpoint
+   - Dynamic `/sitemap.xml` endpoint
+   - Dynamic `/robots.txt` with host filtering
+
+   See [src/routes/(meta)/README.md](./src/routes/(meta)/README.md) for
+   complete documentation.
+
 ### Logging System
 
 The library includes a comprehensive logging system that provides:
@@ -220,34 +277,112 @@ pnpm run upgrade:all # Update all packages
 pnpm run publish:npm # Version bump and publish to npm
 ```
 
-### Import JS, Svelte files and Typedefs
+### Import Patterns and Export Structure
 
-Main folders in lib have an index.js, but may also have a more specific export file e.g. http.js or cache.js (@see $lib/network).
+**Public exports use domain-specific files matching folder names:**
 
-Main folders (should) have a typedef.js that can be used in JSdoc comments.
+```js
+// Standard pattern: folder → matching .js export file
+import { httpGet, httpPost } from '@hkdigital/lib-core/network/http.js';
+import { CacheManager } from '@hkdigital/lib-core/network/cache.js';
+import { LCHAR } from '@hkdigital/lib-core/constants/regexp.js';
+import { Button } from '@hkdigital/lib-core/ui/primitives.js';
+```
+
+**Pattern:**
+- Folder `$lib/network/http/` → Export file `$lib/network/http.js`
+- Folder `$lib/network/cache/` → Export file `$lib/network/cache.js`
+- Folder `$lib/constants/regexp/` → Export file `$lib/constants/regexp.js`
+
+**Rare exception - index.js for aggregated APIs:**
 
 ```js
-// Import Latin char constant for use in regular expressions
-import { LCHAR } from '@hkdigital/lib-core/constants/regexp/index.js';
+// Only used for large subsystems with public-facing aggregated APIs
+import { designTokens } from '@hkdigital/lib-core/design/index.js';
 ```
 
+**TypeDefs for JSDoc:**
+
 ```js
 /**
- * @param {import('@hkdigital/lib-core/network/typedef.js').JsonGetOptions} JsonGetOptions
+ * @param {import('@hkdigital/lib-core/network/typedef.js').HttpGetOptions}
+ *   options
  */
+function fetchData(options) {
+  // ...
+}
 ```
 
-### Import CSS
+### CSS Architecture (app.css)
 
-Vite should include postcss-import, but the only solution to get it working for now is to use a relative path to the node_modules folder.
+**CRITICAL**: Your `src/app.css` must include the complete design system
+architecture. Incomplete imports will cause build failures.
 
-For example:
+**Required structure:**
 
 ```css
 /* src/app.css */
-@import '../node_modules/@hkdigital/lib-core/dist/css/utilities.css';
+
+/* 1. CSS Layers - Controls style precedence */
+@layer theme, base, utilities, components;
+
+/* 2. Tailwind CSS Core */
+@import 'tailwindcss';
+
+/* 3. HKdigital Design System Theme (ALL required for colors to work) */
+@import '../node_modules/@hkdigital/lib-core/dist/design/themes/hkdev/theme.css' layer(theme);
+@import '../node_modules/@hkdigital/lib-core/dist/design/themes/hkdev/globals.css';
+@import '../node_modules/@hkdigital/lib-core/dist/design/themes/hkdev/components.css' layer(components);
+@import '../node_modules/@hkdigital/lib-core/dist/design/themes/hkdev/responsive.css';
+
+/* 4. Skeleton UI Framework */
+@import '@skeletonlabs/skeleton' source('../node_modules/@skeletonlabs/skeleton-svelte/dist');
+@import '@skeletonlabs/skeleton/optional/presets' source('../node_modules/@skeletonlabs/skeleton-svelte/dist');
+
+/* 5. Tailwind Configuration Reference */
+@config "../tailwind.config.js";
+
+/* 6. Optional: Additional utilities */
+/*@import '../node_modules/@hkdigital/lib-core/dist/css/utilities.css';*/
 ```
 
+**Why all theme files are required:**
+- Missing any theme file will cause "Cannot apply unknown utility class"
+  errors
+- Classes like `bg-surface-100`, `text-primary-500` won't work without
+  complete theme
+- All four theme files (theme.css, globals.css, components.css,
+  responsive.css) are needed
+
+See [src/lib/design/README.md](./src/lib/design/README.md) for complete
+CSS architecture documentation.
+
+### Critical: data-theme Attribute
+
+**IMPORTANT**: Add `data-theme="hkdev"` to your `<body>` element in
+`src/app.html`. Without this, theme colors will not work correctly.
+
+```html
+<!-- src/app.html -->
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    %sveltekit.head%
+  </head>
+  <body data-theme="hkdev" data-sveltekit-preload-data="hover">
+    <div>%sveltekit.body%</div>
+  </body>
+</html>
+```
+
+**Why this is required:**
+- Theme CSS custom properties are scoped to `[data-theme='hkdev']`
+- Without this attribute, colors fall back to browser defaults
+- **Symptom**: Colors like `bg-primary-500` show grey instead of magenta
+- **Solution**: Add `data-theme="hkdev"` to `<body>` element
+
 ## Building the library
 
 To build your library:

package/dist/meta/robots/index.d.ts

@@ -0,0 +1,37 @@
+/** @typedef {import('./typedef.js').RobotsConfig} RobotsConfig */
+/**
+ * Check if hostname matches allowed hosts pattern
+ *
+ * @param {string} hostname - Hostname to check (e.g., test.mysite.com)
+ * @param {string[] | '*' | undefined} allowedHosts - Allowed host patterns
+ *
+ * @returns {boolean} True if host is allowed
+ */
+export function isHostAllowed(hostname: string, allowedHosts: string[] | "*" | undefined): boolean;
+/**
+ * Generate robots.txt with sitemap reference
+ *
+ * NOTE: If deployed behind a reverse proxy (nginx, Cloudflare, etc.),
+ * ensure your adapter is configured to trust proxy headers for correct
+ * origin detection:
+ *
+ * // svelte.config.js
+ * export default {
+ *   kit: {
+ *     adapter: adapter({
+ *       // Trust X-Forwarded-* headers from proxy
+ *       trustProxy: true
+ *     })
+ *   }
+ * };
+ *
+ * Without this, url.origin may be http://localhost instead of your
+ * actual domain, and the sitemap directive will be omitted.
+ *
+ * @param {URL} url - Request URL object
+ * @param {RobotsConfig} [config] - Robots configuration object
+ *
+ * @returns {string} robots.txt content
+ */
+export function generateRobotsTxt(url: URL, config?: RobotsConfig): string;
+export type RobotsConfig = import("./typedef.js").RobotsConfig;

package/dist/meta/robots/index.js

@@ -0,0 +1,83 @@
+/** @typedef {import('./typedef.js').RobotsConfig} RobotsConfig */
+
+/**
+ * Check if hostname matches allowed hosts pattern
+ *
+ * @param {string} hostname - Hostname to check (e.g., test.mysite.com)
+ * @param {string[] | '*' | undefined} allowedHosts - Allowed host patterns
+ *
+ * @returns {boolean} True if host is allowed
+ */
+export function isHostAllowed(hostname, allowedHosts) {
+  // If not configured or set to '*', allow all hosts
+  if (!allowedHosts || allowedHosts === '*') {
+    return true;
+  }
+
+  if (typeof allowedHosts === 'string') {
+    allowedHosts = [allowedHosts];
+  }
+
+  // Check if hostname matches any allowed pattern
+  return allowedHosts.some((pattern) => {
+    // Convert wildcard pattern to regex
+    // Example: *.mysite.com -> ^.*\.mysite\.com$
+    const regexPattern = pattern
+      .replace(/\./g, '\\.') // Escape dots
+      .replace(/\*/g, '.*'); // * becomes .*
+
+    const regex = new RegExp(`^${regexPattern}$`, 'i');
+    return regex.test(hostname);
+  });
+}
+
+/**
+ * Generate robots.txt with sitemap reference
+ *
+ * NOTE: If deployed behind a reverse proxy (nginx, Cloudflare, etc.),
+ * ensure your adapter is configured to trust proxy headers for correct
+ * origin detection:
+ *
+ * // svelte.config.js
+ * export default {
+ *   kit: {
+ *     adapter: adapter({
+ *       // Trust X-Forwarded-* headers from proxy
+ *       trustProxy: true
+ *     })
+ *   }
+ * };
+ *
+ * Without this, url.origin may be http://localhost instead of your
+ * actual domain, and the sitemap directive will be omitted.
+ *
+ * @param {URL} url - Request URL object
+ * @param {RobotsConfig} [config] - Robots configuration object
+ *
+ * @returns {string} robots.txt content
+ */
+export function generateRobotsTxt(url, config = {}) {
+  const hostAllowed = isHostAllowed(url.hostname, config.allowedHosts);
+
+  // Block entire site if host is not allowed
+  if (!hostAllowed) {
+    return 'User-agent: *\nDisallow: /';
+  }
+
+  // Allow site, but add specific path blocks
+  let content = 'User-agent: *\nAllow: /';
+
+  // Add disallowed paths
+  if (config.disallowedPaths && config.disallowedPaths.length > 0) {
+    config.disallowedPaths.forEach((path) => {
+      content += `\nDisallow: ${path}`;
+    });
+  }
+
+  // Add sitemap reference if enabled and origin is available
+  if (url.origin && config.includeSitemap !== false) {
+    content += `\nSitemap: ${url.origin}/sitemap.xml`;
+  }
+
+  return content;
+}

package/dist/meta/robots/typedef.d.ts

@@ -0,0 +1,17 @@
+declare const _default: {};
+export default _default;
+export type RobotsConfig = {
+    /**
+     * Allowed host patterns. Use '*' or omit to allow all hosts.
+     * Supports wildcards (e.g., '*.example.com')
+     */
+    allowedHosts?: string[] | "*" | undefined;
+    /**
+     * Paths to block from indexing (e.g., '/admin', '/api/*')
+     */
+    disallowedPaths?: string[] | undefined;
+    /**
+     * Include sitemap reference in robots.txt (default: true)
+     */
+    includeSitemap?: boolean | undefined;
+};

package/dist/meta/robots/typedef.js

@@ -0,0 +1,12 @@
+/**
+ * @typedef {Object} RobotsConfig
+ * @property {string[] | '*'} [allowedHosts]
+ *   Allowed host patterns. Use '*' or omit to allow all hosts.
+ *   Supports wildcards (e.g., '*.example.com')
+ * @property {string[]} [disallowedPaths]
+ *   Paths to block from indexing (e.g., '/admin', '/api/*')
+ * @property {boolean} [includeSitemap]
+ *   Include sitemap reference in robots.txt (default: true)
+ */
+
+export default {};

package/dist/meta/robots.d.ts

@@ -0,0 +1 @@
+export { generateRobotsTxt, isHostAllowed } from "./robots/index.js";

package/dist/meta/robots.js

@@ -0,0 +1,5 @@
+/**
+ * Public exports for robots.txt utilities
+ */
+
+export { generateRobotsTxt, isHostAllowed } from './robots/index.js';

package/dist/meta/sitemap/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Generate sitemap XML
+ *
+ * @param {string} origin - Base URL (e.g., https://example.com)
+ * @param {SitemapRoute[]} [routes=[]] - Array of routes
+ *
+ * @returns {string} XML sitemap
+ */
+export function generateSitemap(origin: string, routes?: SitemapRoute[]): string;
+export type SitemapRoute = import("./typedef.js").SitemapRoute;
+export type SitemapRouteObject = import("./typedef.js").SitemapRouteObject;

package/dist/meta/sitemap/index.js

@@ -0,0 +1,63 @@
+// @see https://www.sitemaps.org/protocol.html
+
+/** @typedef {import('./typedef.js').SitemapRoute} SitemapRoute */
+/** @typedef {import('./typedef.js').SitemapRouteObject} SitemapRouteObject */
+
+/**
+ * Normalize route to full route object with defaults
+ *
+ * @param {import('./typedef.js').SitemapRoute} route - Route path string or route object
+ *
+ * @returns {SitemapRouteObject} Normalized route object
+ */
+function normalizeRoute(route) {
+  // Handle simple string format
+  if (typeof route === 'string') {
+    return {
+      path: route,
+      priority: route === '/' ? 1.0 : 0.8,
+      changefreq: route === '/' ? 'daily' : 'weekly'
+    };
+  }
+
+  // Handle object format with defaults
+  return {
+    priority: 0.8,
+    changefreq: 'weekly',
+    ...route
+  };
+}
+
+/**
+ * Generate sitemap XML
+ *
+ * @param {string} origin - Base URL (e.g., https://example.com)
+ * @param {SitemapRoute[]} [routes=[]] - Array of routes
+ *
+ * @returns {string} XML sitemap
+ */
+export function generateSitemap(origin, routes = []) {
+  // Ensure root path is always included (failsafe)
+  const hasRoot = routes.some((route) => {
+    const path = typeof route === 'string' ? route : route.path;
+    return path === '/';
+  });
+
+  const normalizedRoutes = hasRoot ? routes : ['/', ...routes];
+
+  const urls = normalizedRoutes
+    .map(normalizeRoute)
+    .map(
+      (route) => `
+  <url>
+    <loc>${origin}${route.path}</loc>
+    <changefreq>${route.changefreq}</changefreq>
+    <priority>${route.priority}</priority>
+  </url>`
+    )
+    .join('');
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">${urls}
+</urlset>`;
+}

package/dist/meta/sitemap/typedef.d.ts

@@ -0,0 +1,20 @@
+declare const _default: {};
+export default _default;
+export type SitemapRouteObject = {
+    /**
+     * - Route path (e.g., '/about')
+     */
+    path: string;
+    /**
+     * - Priority (0.0 to 1.0)
+     */
+    priority?: number | undefined;
+    /**
+     * - Change frequency
+     */
+    changefreq?: "hourly" | "daily" | "weekly" | "always" | "monthly" | "yearly" | "never" | undefined;
+};
+/**
+ * Route can be a simple string path or an object with details
+ */
+export type SitemapRoute = string | SitemapRouteObject;

package/dist/meta/sitemap/typedef.js

@@ -0,0 +1,14 @@
+/**
+ * @typedef {Object} SitemapRouteObject
+ * @property {string} path - Route path (e.g., '/about')
+ * @property {number} [priority] - Priority (0.0 to 1.0)
+ * @property {'always'|'hourly'|'daily'|'weekly'|'monthly'|'yearly'|'never'}
+ *   [changefreq] - Change frequency
+ */
+
+/**
+ * @typedef {string | SitemapRouteObject} SitemapRoute
+ *   Route can be a simple string path or an object with details
+ */
+
+export default {};

package/dist/meta/sitemap.d.ts

@@ -0,0 +1 @@
+export { generateSitemap } from "./sitemap/index.js";

package/dist/meta/sitemap.js

@@ -0,0 +1,5 @@
+/**
+ * Public exports for sitemap utilities
+ */
+
+export { generateSitemap } from './sitemap/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hkdigital/lib-core",
-	"version": "0.5.11",
+	"version": "0.5.13",
 	"author": {
 		"name": "HKdigital",
 		"url": "https://hkdigital.nl"