@hkdigital/lib-core 0.3.10 → 0.3.12

package/dist/config/README.md

@@ -0,0 +1,197 @@
+# Config
+
+Reusable configuration generators for HKdigital projects.
+
+## Vite Configuration
+
+The `vite.js` provides generators for common Vite setups used across HKdigital projects.
+
+### Quick Start
+
+```javascript
+// vite.config.js
+import { defineConfig } from 'vitest/config';
+import { sveltekit } from '@sveltejs/kit/vite';
+import { generateViteConfig } from '@hkdigital/lib-sveltekit/config/vite.js';
+
+export default defineConfig(
+  await generateViteConfig({
+    enableImagetools: true
+  })
+);
+```
+
+### Functions
+
+#### `generateViteConfig(options)`
+
+Generates a complete Vite configuration with HKdigital defaults.
+
+**Options:**
+- `enableImagetools` (boolean, default: `true`) - Include vite-imagetools plugin
+- `enableVitest` (boolean, default: `true`) - Include Vitest test configuration
+- `enableSvelteKit` (boolean, default: `true`) - Include SvelteKit plugin
+- `customDefines` (object, default: `{}`) - Additional define values
+- `customPlugins` (array, default: `[]`) - Additional Vite plugins
+- `imagetoolsOptions` (object, default: `{}`) - Options passed to imagetools config
+- `packageJsonPath` (string, default: `'./package.json'`) - Path to package.json
+
+**Built-in defines:**
+- `import.meta.env.VITE_APP_VERSION` - Version from package.json
+- `import.meta.env.VITE_BUILD_TIMESTAMP` - Build timestamp
+
+**Example:**
+```javascript
+export default defineConfig(
+  await generateViteConfig({
+    enableImagetools: true,
+    enableVitest: true,
+    customDefines: {
+      'import.meta.env.VITE_API_URL': JSON.stringify('https://api.example.com')
+    },
+    imagetoolsOptions: {
+      widths: [640, 1024, 1536, 1920]
+    }
+  })
+);
+```
+
+#### `generateViteDefines(options)`
+
+Generates only the define configuration (no plugins).
+
+**Options:**
+- `packageJsonPath` (string, default: `'./package.json'`) - Path to package.json
+- `customDefines` (object, default: `{}`) - Additional define values
+
+**Example:**
+```javascript
+export default defineConfig({
+  plugins: [sveltekit()],
+  define: generateViteDefines({
+    customDefines: {
+      'import.meta.env.VITE_API_URL': JSON.stringify(process.env.API_URL)
+    }
+  })
+});
+```
+
+#### `generateVitestConfig(options)`
+
+Generates only the Vitest test configuration.
+
+**Options:**
+- `additionalPatterns` (array, default: `[]`) - Additional test file patterns
+
+**Example:**
+```javascript
+export default defineConfig({
+  plugins: [sveltekit()],
+  test: generateVitestConfig({
+    additionalPatterns: ['tests/**/*.integration.js']
+  })
+});
+```
+
+## Imagetools Configuration
+
+When `enableImagetools: true`, the following dependencies are required in your project:
+
+```bash
+pnpm add -D vite-imagetools
+```
+
+### TypeScript Support
+
+For TypeScript and JavaScript projects using VS Code or other TypeScript-aware editors, add to your `app.d.ts`:
+
+```typescript
+import '@hkdigital/lib-sveltekit/config/imagetools.d.ts';
+```
+
+**Why this is needed:**
+- Provides type definitions for image imports with query parameters (e.g., `hero.jpg?preset=photo`)
+- Enables IntelliSense and autocompletion for imagetools directives in your editor
+- Prevents TypeScript errors when importing processed images
+- Works for both TypeScript and JavaScript projects (VS Code uses TypeScript for JS intellisense)
+
+**What it enables:**
+```javascript
+// These imports will have proper typing and editor support
+import heroImage from '$lib/assets/hero.jpg?preset=photo';
+import heroResponsive from '$lib/assets/hero.jpg?preset=photo&responsive';
+```
+
+### Image Usage
+
+With imagetools enabled, you can use images with processing directives:
+
+```javascript
+// Basic usage
+import heroImage from '$lib/assets/hero.jpg?preset=photo';
+
+// Responsive images
+import heroResponsive from '$lib/assets/hero.jpg?preset=photo&responsive';
+```
+
+**Available presets:**
+- `default` - AVIF format, 90% quality
+- `photo` - JPG format, 95% quality, returns metadata
+- `render` - JPG format, 95% quality, returns metadata
+- `gradient` - JPG format, 95% quality, returns metadata
+- `drawing` - AVIF format, 90% quality, returns metadata
+- `savedata` - AVIF format, 85% quality, returns metadata
+- `blur` - AVIF format, 50% quality with blur effect, returns metadata
+
+## Migration from Direct Config
+
+### Before
+```javascript
+// vite.config.js
+import { defineConfig } from 'vitest/config';
+import { sveltekit } from '@sveltejs/kit/vite';
+import { imagetools } from 'vite-imagetools';
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+
+import {
+  generateDefaultDirectives,
+  generateResponseConfigs
+} from '@hkdigital/lib-sveltekit/config/imagetools-config.js';
+
+const packageJson = JSON.parse(
+  readFileSync(resolve('./package.json'), 'utf-8')
+);
+
+export default defineConfig({
+  plugins: [
+    sveltekit(),
+    imagetools({
+      defaultDirectives: generateDefaultDirectives(),
+      resolveConfigs: generateResponseConfigs()
+    })
+  ],
+  define: {
+    'import.meta.env.VITE_APP_VERSION': JSON.stringify(packageJson.version),
+    'import.meta.env.VITE_BUILD_TIMESTAMP': JSON.stringify(new Date().toISOString())
+  },
+  test: {
+    include: [
+      'src/**/*.{test,spec}.{js,ts}',
+      'src/**/*.svelte.{test,spec}.{js,ts}'
+    ]
+  }
+});
+```
+
+### After
+```javascript
+// vite.config.js
+import { defineConfig } from 'vitest/config';
+import { sveltekit } from '@sveltejs/kit/vite';
+import { generateViteConfig } from '@hkdigital/lib-sveltekit/config/vite.js';
+
+export default defineConfig(
+  await generateViteConfig()
+);
+```

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

@@ -0,0 +1,47 @@
+/**
+ * Generates a Vite configuration object with common HKdigital settings
+ *
+ * @param {object} [options] Configuration options
+ * @param {boolean} [options.enableImagetools=true] Enable vite-imagetools plugin
+ * @param {boolean} [options.enableVitest=true] Include Vitest configuration
+ * @param {boolean} [options.enableSvelteKit=true] Enable SvelteKit plugin
+ * @param {object} [options.customDefines={}] Additional define values
+ * @param {Array} [options.customPlugins=[]] Additional Vite plugins
+ * @param {object} [options.imagetoolsOptions={}] Options for imagetools config
+ * @param {string} [options.packageJsonPath='./package.json'] Path to package.json
+ *
+ * @returns {Promise<object>} Vite configuration object
+ */
+export function generateViteConfig(options?: {
+    enableImagetools?: boolean;
+    enableVitest?: boolean;
+    enableSvelteKit?: boolean;
+    customDefines?: object;
+    customPlugins?: any[];
+    imagetoolsOptions?: object;
+    packageJsonPath?: string;
+}): Promise<object>;
+/**
+ * Generates build-time defines for Vite
+ *
+ * @param {object} [options] Configuration options
+ * @param {string} [options.packageJsonPath='./package.json'] Path to package.json
+ * @param {object} [options.customDefines={}] Additional define values
+ *
+ * @returns {object} Define configuration object
+ */
+export function generateViteDefines(options?: {
+    packageJsonPath?: string;
+    customDefines?: object;
+}): object;
+/**
+ * Generates Vitest configuration
+ *
+ * @param {object} [options] Configuration options
+ * @param {string[]} [options.additionalPatterns=[]] Additional test patterns
+ *
+ * @returns {object} Vitest configuration object
+ */
+export function generateVitestConfig(options?: {
+    additionalPatterns?: string[];
+}): object;

package/dist/config/generators/vite.js

@@ -0,0 +1,148 @@
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+
+/**
+ * Generates a Vite configuration object with common HKdigital settings
+ *
+ * @param {object} [options] Configuration options
+ * @param {boolean} [options.enableImagetools=true] Enable vite-imagetools plugin
+ * @param {boolean} [options.enableVitest=true] Include Vitest configuration
+ * @param {boolean} [options.enableSvelteKit=true] Enable SvelteKit plugin
+ * @param {object} [options.customDefines={}] Additional define values
+ * @param {Array} [options.customPlugins=[]] Additional Vite plugins
+ * @param {object} [options.imagetoolsOptions={}] Options for imagetools config
+ * @param {string} [options.packageJsonPath='./package.json'] Path to package.json
+ *
+ * @returns {Promise<object>} Vite configuration object
+ */
+export async function generateViteConfig(options = {}) {
+  const {
+    enableImagetools = true,
+    enableVitest = true,
+    enableSvelteKit = true,
+    customDefines = {},
+    customPlugins = [],
+    imagetoolsOptions = {},
+    packageJsonPath = './package.json'
+  } = options;
+
+  // Read package.json for version
+  const packageJson = JSON.parse(
+    readFileSync(resolve(packageJsonPath), 'utf-8')
+  );
+
+  const plugins = [...customPlugins];
+
+  // Add SvelteKit plugin (provides $lib alias and other SvelteKit features)
+  if (enableSvelteKit) {
+    try {
+      const { sveltekit } = await import('@sveltejs/kit/vite');
+      plugins.push(sveltekit());
+    } catch (error) {
+      console.error(error);
+      console.warn(
+        '@sveltejs/kit/vite not found. Install it to enable SvelteKit support.'
+      );
+    }
+  }
+
+  // Conditionally add imagetools
+  if (enableImagetools) {
+    try {
+      const { imagetools } = await import('vite-imagetools');
+      const { 
+        generateDefaultDirectives, 
+        generateResponseConfigs 
+      } = await import('./imagetools.js');
+
+      plugins.push(
+        imagetools({
+          defaultDirectives: generateDefaultDirectives(imagetoolsOptions),
+          resolveConfigs: generateResponseConfigs(imagetoolsOptions)
+        })
+      );
+    } catch (error) {
+      const errorMessage = `
+╭─────────────────────────────────────────────────────────────╮
+│                     Missing Dependency                      │
+├─────────────────────────────────────────────────────────────┤
+│  'vite-imagetools' is required when enableImagetools: true  │
+│  Install it with: pnpm add -D vite-imagetools               │
+│  Or set enableImagetools: false                             │
+╰─────────────────────────────────────────────────────────────╯`;
+      console.error(errorMessage);
+      throw new Error('vite-imagetools is required when enableImagetools: true');
+    }
+  }
+
+  const config = {
+    plugins,
+    define: {
+      'import.meta.env.VITE_APP_VERSION': JSON.stringify(packageJson.version),
+      'import.meta.env.VITE_BUILD_TIMESTAMP': JSON.stringify(
+        new Date().toISOString()
+      ),
+      ...customDefines
+    }
+  };
+
+  if (enableVitest) {
+    config.test = {
+      include: [
+        'src/**/*.{test,spec}.{js,ts}',
+        'src/**/*.svelte.{test,spec}.{js,ts}'
+      ]
+    };
+  }
+
+  return config;
+}
+
+/**
+ * Generates build-time defines for Vite
+ *
+ * @param {object} [options] Configuration options
+ * @param {string} [options.packageJsonPath='./package.json'] Path to package.json
+ * @param {object} [options.customDefines={}] Additional define values
+ *
+ * @returns {object} Define configuration object
+ */
+export function generateViteDefines(options = {}) {
+  const {
+    packageJsonPath = './package.json',
+    customDefines = {}
+  } = options;
+
+  const packageJson = JSON.parse(
+    readFileSync(resolve(packageJsonPath), 'utf-8')
+  );
+
+  return {
+    'import.meta.env.VITE_APP_VERSION': JSON.stringify(packageJson.version),
+    'import.meta.env.VITE_BUILD_TIMESTAMP': JSON.stringify(
+      new Date().toISOString()
+    ),
+    ...customDefines
+  };
+}
+
+/**
+ * Generates Vitest configuration
+ *
+ * @param {object} [options] Configuration options
+ * @param {string[]} [options.additionalPatterns=[]] Additional test patterns
+ *
+ * @returns {object} Vitest configuration object
+ */
+export function generateVitestConfig(options = {}) {
+  const { additionalPatterns = [] } = options;
+
+  const defaultPatterns = [
+    'src/**/*.{test,spec}.{js,ts}',
+    'src/**/*.svelte.{test,spec}.{js,ts}'
+  ];
+
+  return {
+    include: [...defaultPatterns, ...additionalPatterns]
+  };
+}

package/dist/config/imagetools.d.ts

@@ -1,5 +1,5 @@
-type ImageMeta = import('../typedef').ImageMeta;
-type ImageSource = import('../typedef').ImageSource;
+type ImageMeta = import('../network/typedef.js').ImageMeta;
+type ImageSource = import('../network/typedef.js').ImageSource;
 
 declare module '*?responsive' {
   const out: ImageMeta[];

package/dist/config/vite.d.ts

@@ -0,0 +1 @@
+export { generateViteConfig, generateViteDefines, generateVitestConfig } from "./generators/vite.js";

package/dist/config/vite.js

@@ -0,0 +1,5 @@
+export { 
+  generateViteConfig,
+  generateViteDefines,
+  generateVitestConfig
+} from './generators/vite.js';

package/dist/constants/regexp/README.md

@@ -0,0 +1,96 @@
+# Regular Expression Constants
+
+This directory contains regular expression patterns and components for validating text, user data, and URL formats.
+
+## Overview
+
+All regular expressions use the `v` flag (Unicode Sets mode) for consistent Unicode support and advanced character class operations.
+
+## Unicode Property Escapes
+
+### Character Types
+
+- **Letter (any language)**: `\p{L}`
+- **Letter (Latin only)**: `\p{Script=Latin}`
+- **Number (any language)**: `\p{N}`
+- **Number (decimal digits only)**: `\p{Nd}` - excludes roman numerals
+
+### Available Constants
+
+From `text.js`:
+- `LCHAR` - Latin script characters: `\p{Script=Latin}`
+- `LNUMBER` - Latin decimal digits: `[0-9]`
+- `LCHAR_LNUMBER` - Combination of Latin characters and Latin decimal numbers
+- `EMOJI` - RGI Emoji: `\p{RGI_Emoji}`
+- `PUNCT` - Basic punctuation marks: `\p{Punctuation}`
+- `PUNCT_RICH` - All Unicode punctuation: `\p{P}`
+
+## Usage Examples
+
+### Basic Usage
+```js
+import { LCHAR, LNUMBER } from '$lib/constants/regexp/text.js';
+
+// Use with 'v' flag for Unicode Sets mode
+const re = new RegExp(`^(?:${LCHAR}|${LNUMBER})+$`, 'v');
+```
+
+### Character Classes vs Groups
+```js
+// ❌ Don't use Unicode properties in character classes with 'v' flag
+const invalid = new RegExp(`^[${LCHAR}]$`, 'v'); // Error
+
+// ✅ Use non-capturing groups instead
+const valid = new RegExp(`^(?:${LCHAR})$`, 'v'); // Works
+```
+
+## Flag Usage
+
+### The `v` Flag (Unicode Sets Mode)
+- Enables advanced Unicode support
+- Supports set operations: `[A--B]`, `[A&&B]`, `[A||B]`
+- Better emoji and complex Unicode sequence handling
+- Stricter syntax requirements than `u` flag
+
+### RGI Emoji Support
+The `v` flag enables support for "Recommended for General Interchange" emoji, allowing matching of emoji regardless of their internal code point complexity.
+
+```js
+const emojiPattern = new RegExp(`^(?:${EMOJI})$`, 'v');
+emojiPattern.test('😄'); // true
+emojiPattern.test('👨🏾‍⚕️'); // true (complex multi-codepoint emoji)
+```
+
+## File Structure
+
+- `text.js` - Basic Unicode character type constants
+- `user.js` - User data validation patterns (names, usernames, etc.)
+- `url.js` - URL and slug validation patterns
+- `index.js` - Exports all regexp constants
+- `*.test.js` - Test files for each module
+
+## Validation Patterns
+
+### User Data (user.js)
+- `RE_NAME` - Personal names with Latin characters
+- `RE_FULLNAME` - Full names with space separators
+- `RE_SURNAME` - Surnames with optional prefixes
+- `RE_USERNAME` - Usernames with alphanumeric and limited special characters
+- `RE_PHONENUMBER` - Phone number formats
+
+### URL Data (url.js)
+- `URL_SLUG` - URL-safe slugs for paths (e.g., "my-blog-post")
+
+## Browser Support
+
+The `v` flag requires modern browser support:
+- Chrome 112+ (March 2023)
+- Firefox 116+ (August 2023)
+- Safari 17+ (September 2023)
+- Node.js 20+ (April 2023)
+
+## References
+
+- [Unicode Character Properties](https://en.wikipedia.org/wiki/Unicode_character_property#General_Category)
+- [RegExp v flag specification](https://v8.dev/features/regexp-v-flag)
+- [MDN Unicode character class escape](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Unicode_character_class_escape)

package/dist/constants/regexp/index.d.ts

@@ -1,3 +1,3 @@
 export * from "./text.js";
 export * from "./user.js";
-export * from "./web.js";
+export * from "./url.js";

package/dist/constants/regexp/index.js

@@ -12,7 +12,7 @@
  * such a some emoji, you must use the flag 'v'.
  *
  * @eg
- * const re = new RegExp('^[${Latin_Number}]', 'u');
+ * const re = new RegExp('^(?:${Latin_Number})', 'v');
  *
  * @eg
  * const re = new RegExp('^[${Symbols_Emoji}]', 'v');
@@ -28,4 +28,4 @@
  */
 export * from './text.js';
 export * from './user.js';
-export * from './web.js';
+export * from './url.js';

package/dist/constants/regexp/text.d.ts

@@ -11,7 +11,7 @@
  * import { Latin_Char_Number as lcn } from './latin.js';
  * export const User_Username = `^[${lcn}]+${lcn}_-]{1,38}[${lcn}]$`;
  *
- * const re = new RegExp('^[${Latin_Number}]', 'u');
+ * const re = new RegExp('^(?:${Latin_Number})', 'v');
  *
  * Emoji:
  *
@@ -39,9 +39,9 @@
  * @see https://en.wikipedia.org/
  *      wiki/Unicode_character_property#General_Category
  */
-export const CHAR: "\\p{Script=Latin}";
-export const NUMBER: "\\p{Nd}";
-export const CHAR_NUMBER: "\\p{Script=Latin}\\p{Nd}";
+export const LCHAR: "\\p{Script=Latin}";
+export const LNUMBER: "[0-9]";
+export const LCHAR_LNUMBER: "\\p{Script=Latin}|[0-9]";
 export const EMOJI: "\\p{RGI_Emoji}";
-export const PUNCTUATION: "\\p{Punctuation}$+<=>\\^`\\|~";
-export const PUNCT: "\\p{Punctuation}$+<=>\\^`\\|~";
+export const PUNCT: "\\p{Punctuation}";
+export const PUNCT_RICH: "\\p{P}";

package/dist/constants/regexp/text.js

@@ -11,7 +11,7 @@
  * import { Latin_Char_Number as lcn } from './latin.js';
  * export const User_Username = `^[${lcn}]+${lcn}_-]{1,38}[${lcn}]$`;
  *
- * const re = new RegExp('^[${Latin_Number}]', 'u');
+ * const re = new RegExp('^(?:${Latin_Number})', 'v');
  *
  * Emoji:
  *
@@ -40,10 +40,10 @@
  *      wiki/Unicode_character_property#General_Category
  */
 
-export const CHAR = '\\p{Script=Latin}';
-export const NUMBER = '\\p{Nd}';
-export const CHAR_NUMBER = `${CHAR}${NUMBER}`;
+export const LCHAR = '\\p{Script=Latin}';
+export const LNUMBER = '[0-9]';
+export const LCHAR_LNUMBER = `${LCHAR}|${LNUMBER}`;
 
 export const EMOJI = '\\p{RGI_Emoji}';
-export const PUNCTUATION = '\\p{Punctuation}$+<=>\\^`\\|~';
-export const PUNCT = PUNCTUATION;
+export const PUNCT = '\\p{Punctuation}';
+export const PUNCT_RICH = '\\p{P}';

package/dist/constants/regexp/url.d.ts

@@ -0,0 +1 @@
+export const URL_SLUG: "^[a-zA-Z0-9]+(?:-[a-zA-Z0-9]+)*$";

package/dist/constants/regexp/url.js

@@ -0,0 +1,3 @@
+import { LCHAR, NUMBER } from './text.js';
+
+export const URL_SLUG = `^[a-zA-Z0-9]+(?:-[a-zA-Z0-9]+)*$`;

package/dist/constants/regexp/user.d.ts

@@ -2,5 +2,4 @@ export const RE_NAME: RegExp;
 export const RE_FULLNAME: RegExp;
 export const RE_SURNAME: RegExp;
 export const RE_USERNAME: RegExp;
-export const RE_EMAIL: RegExp;
 export const RE_PHONENUMBER: RegExp;

package/dist/constants/regexp/user.js

@@ -6,28 +6,24 @@
  * @see https://ihateregex.io/expr/discord-username/
  */
 
-import { NUMBER as N, CHAR, CHAR_NUMBER as CN } from './text.js';
+import { LNUMBER as N, LCHAR, LCHAR_LNUMBER as CN } from './text.js';
 
 export const RE_NAME = new RegExp(
-  `^[${CHAR}]+(([\\s'\\-\\.]{1}|[\\s]{1}[']{0,1})[${CHAR}]+){0,8}$`, 'v'
+  `^[${LCHAR}]+(([\\s'\\-\\.]{1}|[\\s]{1}[']{0,1})[${LCHAR}]+){0,8}$`, 'v'
 );
 
 export const RE_FULLNAME = new RegExp(
-  `^[${CHAR}]{2,}[\\s][']?[${CHAR}]{1,}([\\s]?['\\-]?[${CHAR}]{1,})*$`, 'v'
+  `^[${LCHAR}]{2,}[\\s][']?[${LCHAR}]{1,}([\\s]?['\\-]?[${LCHAR}]{1,})*$`, 'v'
 );
 
 export const RE_SURNAME = new RegExp(
-  `^[']?[${CHAR}]{1,}([\\s]?['\\-]?[${CHAR}]{1,})*$`, 'v'
+  `^[']?[${LCHAR}]{1,}([\\s]?['\\-]?[${LCHAR}]{1,})*$`, 'v'
 )
 
 export const RE_USERNAME = new RegExp(
-  `^[${CN}]{2,40}([\\-_\\.][${CN}]{1,40}){0,3}([#][${N}]{1,10}){0,1}$`, 'v'
-);
-
-export const RE_EMAIL = new RegExp(
-  `[^@ \t\r\n]+@[^@ \t\r\n]+\.[^@ \t\r\n]+`, 'v'
+  `^(?:${CN}){2,40}([\\-_\\.](?:${CN}){1,40}){0,3}([#](?:${N}){1,10}){0,1}$`, 'v'
 );
 
 export const RE_PHONENUMBER = new RegExp(
   `^[\\+]?[\\(]?[0-9]{3}[\\)]?[\\-\\s\\.]?[0-9]{3}[\\-\\s\\.]?[0-9]{4,6}$`, 'v'
-)
+)