@hkdigital/lib-core 0.5.11 → 0.5.12

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/package.json

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