@hkdigital/lib-core 0.4.4 → 0.4.6

package/README.md

@@ -9,39 +9,120 @@ It contains common code, base components and documentation that help you with se
 
 ### Install
 
-The library can be installed as a normal NPM library.
-
+**For projects/applications:**
 ```bash
 pnpm add @hkdigital/lib-core
 ```
 
-### Peer Dependencies
-
-This library requires certain peer dependencies depending on which features you use:
-
-**For development logging:**
-```bash
-pnpm add -D pino-pretty
-```
-
-**For Vite config generators with imagetools:**
+**For other libraries:**
 ```bash
-pnpm add -D vite-imagetools
+pnpm add -D --save-peer @hkdigital/lib-core
 ```
 
-#### Tailwind
-
-Components in this package use [tailwindcss](https://tailwindcss.com/).
-
-To compile tailwind classes inside this package, you must add the package location to your tailwindcss plugin configuration.
+### Peer Dependencies
 
-```
-// tailwind.config.js
-export default {
-  content: [
-    './node_modules/@hkdigital/**/*.{html,js,svelte,ts}',
-    './src/**/*.{html,js,svelte,ts}',
-```
+Install peer dependencies:
+```bash
+# Core framework and utilities
+pnpm add @sveltejs/kit svelte svelte-preprocess runed valibot
+
+# UI components and icons
+pnpm add @steeze-ui/heroicons
+
+# Logging
+pnpm add pino pino-pretty
+
+# Linting
+pnpm add @eslint/js eslint-plugin-import
+```
+
+### Design System & Configuration
+
+This library includes a complete design system with Tailwind CSS integration. Basic setup requires:
+
+1. **Tailwind config** - Include library files in content scanning:
+   ```js
+   // tailwind.config.js
+   import { 
+     generateTailwindThemeExtensions,
+     designTokens,
+     customUtilitiesPlugin 
+   } from '@hkdigital/lib-core/design/index.js';
+
+   const themeExtensions = generateTailwindThemeExtensions(designTokens);
+
+   /** @type {import('tailwindcss').Config} */
+   export default {
+     // Include @hkdigital libraries in content so Tailwind processes
+     // their design system classes and components for proper styling
+     content: [
+       './node_modules/@hkdigital/**/*.{html,js,svelte}',
+       './src/**/*.{html,js,svelte}'
+     ],
+     theme: {
+       // Extend Tailwind's default theme using the design system tokens
+       extend: themeExtensions
+     },
+     plugins: [
+       // Generate custom utility classes like 'type-heading-h2'
+       customUtilitiesPlugin
+     ]
+   };
+   ```
+
+2. **Design tokens** - Apply CSS variables in your layout:
+   ```html
+   <!-- src/routes/+layout.svelte -->
+   <script>
+     import { designTokens, designTokensToRootCssVars } from '@hkdigital/lib-core/design/index.js';
+   </script>
+
+   <svelte:head>
+     {@html designTokensToRootCssVars(designTokens)}
+   </svelte:head>
+
+   {@render children()}
+   ```
+
+3. **Vite configuration** - Use the provided config generator:
+   ```js
+   // vite.config.js
+   import { defineConfig } from 'vitest/config';
+   import { generateViteConfig } from '@hkdigital/lib-core/config/vite.js';
+
+   export default defineConfig(
+     await generateViteConfig({
+       enableImagetools: true,
+       enableVitest: true
+     })
+   );
+   ```
+
+4. **Svelte configuration** - Configure preprocessing and useful path aliases:
+   ```js
+   // svelte.config.js
+   import { sveltePreprocess } from 'svelte-preprocess';
+   import adapter from '@sveltejs/adapter-auto';
+
+   /** @type {import('@sveltejs/kit').Config} */
+   const config = {
+     // Enable preprocessing for external CSS files in Svelte components
+     preprocess: sveltePreprocess({}),
+     kit: {
+       adapter: adapter(),
+       alias: {
+         $src: 'src',
+         $examples: 'src/routes/examples'
+       }
+     }
+   };
+
+   export default config;
+   ```
+
+For detailed setup guides see:
+- **Design system**: [src/lib/design/README.md](./src/lib/design/README.md)
+- **Vite configuration**: [src/lib/config/README.md](./src/lib/config/README.md)
 
 ### Update
 
@@ -52,40 +133,18 @@ in the '@hkdigital' namespace.
 pnpm upgrade:hk
 ```
 
-### The package.json scripts:
+### Available scripts
 
 ```bash
-pnpm add -D npm-check-updates
-pnpm add -D npm-check-updates
+pnpm run dev         # Start development server
+pnpm run build       # Build the library
+pnpm run check       # Type checking and validation
+pnpm run test        # Run unit tests
+pnpm run upgrade:hk  # Update all @hkdigital/... packages
+pnpm run upgrade:all # Update all packages
+pnpm run publish:npm # Version bump and publish to npm
 ```
 
-```js
-"scripts": {
-  "upgrade:hk": "run-s upgrade:hk:update pnpm:install",
-  "upgrade:hk:update": "ncu --dep dev,optional,peer,prod '@hkdigital/*' -u",
-  "pnpm:install": "pnpm install"
-}
-```
-
-### Vite Configuration
-
-The library provides configuration generators for Vite that include common HKdigital project settings:
-
-```javascript
-// vite.config.js
-import { defineConfig } from 'vitest/config';  
-import { generateViteConfig } from '@hkdigital/lib-core/config/vite.js';
-
-export default defineConfig(
-  await generateViteConfig({
-    enableImagetools: true,
-    enableVitest: true
-  })
-);
-```
-
-For detailed configuration options, see the [config documentation](./src/lib/config/README.md).
-
 ### Import JS, Svelte files and Typedefs
 
 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).
@@ -114,18 +173,6 @@ For example:
 @import '../node_modules/@hkdigital/lib-core/dist/css/utilities.css';
 ```
 
-### Enable tailwind processing
-
-Allow the tailwind CSS processor to work on the library inside node_modules
-
-```js
-// tailwind.config.js
-export default {
-  content: [
-    './node_modules/@hkdigital/**/*.{html,js,svelte,ts}',
-    './src/**/*.{html,js,svelte,ts}',
-```
-
 ## Building the library
 
 To build your library:

package/dist/config/README.md

@@ -56,51 +56,21 @@ export default defineConfig(
 );
 ```
 
-#### `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:
+When `enableImagetools: true`, install the imagetools dependency:
 
+**For projects/applications:**
 ```bash
 pnpm add -D vite-imagetools
 ```
 
+**For other libraries:**
+```bash
+pnpm add -D --save-peer vite-imagetools
+```
+
 ### TypeScript Support
 
 For TypeScript and JavaScript projects using VS Code or other TypeScript-aware editors, add to your `app.d.ts`:

package/dist/config/vite.d.ts

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

package/dist/config/vite.js

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

package/dist/ui/dev/explorer/Explorer.svelte

@@ -0,0 +1,300 @@
+<script>
+  import { goto } from '$app/navigation';
+
+  /**
+   * Reusable explorer component for navigating nested folder structures
+   * @type {{
+   *   navigationData: Object,
+   *   currentPath: string,
+   *   getActiveSegments?: (segments: string[]) => void,
+   *   getNavigateToLevelFunction?: (fn: Function) => void,
+   *   rootName?: string,
+   *   folderName?: string
+   * }}
+   */
+  let {
+    navigationData,
+    currentPath = '',
+    getActiveSegments,
+    getNavigateToLevelFunction,
+    rootName = 'Categories',
+    folderName
+  } = $props();
+
+  /** @type {string[]} */
+  let pathSegments = $derived(
+    currentPath ? currentPath.split('/').filter(Boolean) : []
+  );
+
+  /** @type {string[]} */
+  let interactiveSegments = $state([]);
+
+  /** @type {string[]} */
+  let activeSegments = $derived(
+    interactiveSegments.length > 0 ? interactiveSegments : pathSegments
+  );
+
+  // Notify parent of active segments changes - only when they change
+  let lastActiveSegments = [];
+  $effect(() => {
+    if (
+      getActiveSegments &&
+      JSON.stringify(activeSegments) !== JSON.stringify(lastActiveSegments)
+    ) {
+      lastActiveSegments = [...activeSegments];
+      getActiveSegments(activeSegments);
+    }
+  });
+
+  /** @type {Object[]} */
+  let breadcrumbColumns = $derived.by(() => {
+    const columns = [];
+    let current = navigationData;
+
+    // Root column with sorted items (folders first, then endpoints)
+    const rootItems = Object.values(current).map((item) => ({
+      name: item.name,
+      displayName: item.displayName || item.name,
+      isEndpoint: item.isEndpoint,
+      isSelected: activeSegments.length > 0 && 
+        activeSegments[0] === item.name
+    })).sort((a, b) => {
+      // Sort by type first (folders before endpoints)
+      if (a.isEndpoint !== b.isEndpoint) {
+        return a.isEndpoint ? 1 : -1;
+      }
+      // Then sort alphabetically by display name
+      return a.displayName.localeCompare(b.displayName);
+    });
+
+    columns.push({
+      title: rootName,
+      items: rootItems,
+      level: 0
+    });
+
+    // Build columns for each path segment
+    for (let i = 0; i < activeSegments.length; i++) {
+      const segment = activeSegments[i];
+
+      if (current[segment]) {
+        current = current[segment].children;
+
+        if (Object.keys(current).length > 0) {
+          const nextSegment = activeSegments[i + 1];
+
+          // Sort nested items (folders first, then endpoints)
+          const nestedItems = Object.values(current).map((item) => ({
+            name: item.name,
+            displayName: item.displayName || item.name,
+            isEndpoint: item.isEndpoint,
+            isSelected: nextSegment === item.name
+          })).sort((a, b) => {
+            // Sort by type first (folders before endpoints)
+            if (a.isEndpoint !== b.isEndpoint) {
+              return a.isEndpoint ? 1 : -1;
+            }
+            // Then sort alphabetically by display name
+            return a.displayName.localeCompare(b.displayName);
+          });
+
+          columns.push({
+            title: segment,
+            items: nestedItems,
+            level: i + 1
+          });
+        }
+      }
+    }
+
+    return columns;
+  });
+
+  /**
+   * Handle navigation to a folder or endpoint
+   * @param {number} level - Column level
+   * @param {string} itemName - Item name
+   * @param {boolean} isEndpoint - Whether this is a final endpoint
+   */
+  function handleNavigation(level, itemName, isEndpoint) {
+    // Build new path segments up to the selected level
+    const newSegments = [...activeSegments.slice(0, level), itemName];
+    const fullPath = newSegments.join('/');
+
+    // Always navigate to explorer URL - let the route system handle state
+    goto(`/explorer/${folderName}/${fullPath}`);
+  }
+
+  /**
+   * Handle breadcrumb navigation
+   * @param {number} level - Level to navigate back to
+   */
+  function navigateToLevel(level) {
+    if (level === 0) {
+      // Navigate back to root explorer
+      goto('/explorer');
+    } else {
+      // Navigate to specific level
+      const currentSegments =
+        interactiveSegments.length > 0 ? interactiveSegments : pathSegments;
+      const newSegments = currentSegments.slice(0, level);
+      const explorerPath = newSegments.join('/');
+      goto(`/explorer/${folderName}/${explorerPath}`);
+    }
+  }
+
+  // Expose the navigate function to parent
+  if (getNavigateToLevelFunction) {
+    getNavigateToLevelFunction(navigateToLevel);
+  }
+</script>
+
+<div class="explorer-container">
+  <!-- Dynamic columns -->
+  <div class="navigation-columns">
+    {#each breadcrumbColumns as column, columnIndex}
+      <div class="column" data-column={`level-${column.level}`}>
+        <h2 class="type-heading-h2 mb-20up">{column.title}</h2>
+        <nav class="folder-list">
+          {#each column.items as item}
+            <button
+              class="folder-item"
+              class:active={item.isSelected}
+              class:endpoint={item.isEndpoint}
+              onclick={() =>
+                handleNavigation(column.level, item.name, item.isEndpoint)}
+            >
+              <div class="item-content">
+                <div class="item-icon">
+                  {#if item.isEndpoint}
+                    <svg 
+                      class="external-icon" 
+                      viewBox="0 0 16 16" 
+                      fill="currentColor"
+                      aria-hidden="true"
+                    >
+                      <path d="M3.5 2A1.5 1.5 0 002 3.5v9A1.5 1.5 0 003.5 14h9a1.5 1.5 0 001.5-1.5V9.75a.75.75 0 00-1.5 0v2.75a.25.25 0 01-.25.25h-8.5a.25.25 0 01-.25-.25v-8.5a.25.25 0 01.25-.25H6.5a.75.75 0 000-1.5h-3z"/>
+                      <path d="M15.25 1a.75.75 0 00-.75-.75h-4.5a.75.75 0 000 1.5h2.69l-6.22 6.22a.75.75 0 101.06 1.06L13.75 3.31v2.69a.75.75 0 001.5 0V1z"/>
+                    </svg>
+                  {:else}
+                    <svg 
+                      class="folder-icon" 
+                      viewBox="0 0 16 16" 
+                      fill="currentColor"
+                      aria-hidden="true"
+                    >
+                      <path d="M1.75 2A1.75 1.75 0 000 3.75v8.5C0 13.216.784 14 1.75 14h12.5A1.75 1.75 0 0016 12.25v-7.5A1.75 1.75 0 0014.25 3H7.5L6.25 1.75A.75.75 0 005.75 1.5h-4A1.75 1.75 0 000 3.25V3.75z"/>
+                    </svg>
+                  {/if}
+                </div>
+                <span class="item-name">{item.displayName}</span>
+              </div>
+            </button>
+          {/each}
+
+          {#if column.items.length === 0}
+            <div class="empty-state">
+              <p class="type-base-sm">No items found</p>
+            </div>
+          {/if}
+        </nav>
+      </div>
+    {/each}
+  </div>
+</div>
+
+<style>
+  .explorer-container {
+    padding: 20px;
+  }
+
+  .navigation-columns {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
+    gap: 30px;
+    align-items: start;
+  }
+
+  .column {
+    min-height: 200px;
+  }
+
+  .folder-list {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+  }
+
+  .folder-item {
+    display: block;
+    width: 100%;
+    padding: 12px 16px;
+    background: none;
+    border: none;
+    text-align: left;
+    cursor: pointer;
+    color: var(--color-surface-700);
+    transition: all 0.2s;
+    font-size: 14px;
+    line-height: 1.4;
+  }
+
+  .folder-item:hover {
+    background-color: var(--color-surface-100);
+  }
+
+  .folder-item.active {
+    background-color: var(--color-primary-100);
+    color: var(--color-primary-700);
+  }
+
+  .folder-item.endpoint:hover {
+    background-color: var(--color-primary-50);
+    color: var(--color-primary-600);
+  }
+
+  .item-content {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+  }
+
+  .item-icon {
+    display: flex;
+    align-items: center;
+    width: 14px;
+    height: 14px;
+    flex-shrink: 0;
+  }
+
+  .item-name {
+    flex: 1;
+  }
+
+  .external-icon,
+  .folder-icon {
+    width: 14px;
+    height: 14px;
+    opacity: 0.6;
+    transition: opacity 0.2s;
+  }
+
+  .folder-item:hover .external-icon,
+  .folder-item:hover .folder-icon {
+    opacity: 0.8;
+  }
+
+  .folder-item.endpoint .external-icon {
+    color: var(--color-primary-600);
+  }
+
+  .folder-item .folder-icon {
+    color: var(--color-surface-500);
+  }
+
+  .empty-state {
+    padding: 20px;
+    text-align: center;
+    color: var(--color-surface-500);
+  }
+</style>

package/dist/ui/dev/explorer/Explorer.svelte.d.ts

@@ -0,0 +1,20 @@
+export default Explorer;
+type Explorer = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<{
+        navigationData: any;
+        currentPath: string;
+        getActiveSegments?: (segments: string[]) => void;
+        getNavigateToLevelFunction?: (fn: Function) => void;
+        rootName?: string;
+        folderName?: string;
+    }>): void;
+};
+declare const Explorer: import("svelte").Component<{
+    navigationData: any;
+    currentPath: string;
+    getActiveSegments?: (segments: string[]) => void;
+    getNavigateToLevelFunction?: (fn: Function) => void;
+    rootName?: string;
+    folderName?: string;
+}, {}, "">;

package/dist/ui/dev/explorer/TopBar.svelte

@@ -0,0 +1,82 @@
+<script>
+  import { enhance } from '$app/forms';
+
+  import { Panel } from '../../primitives.js';
+
+  /**
+   * @type {{
+   *   scalingEnabled: boolean,
+   *   onchange?: (enabled: boolean) => void,
+   *   crumblePath?: import('svelte').Snippet
+   * }}
+   */
+  let { scalingEnabled = $bindable(), onchange, crumblePath } = $props();
+</script>
+
+<div class="examples-top-bar" data-component="top-bar">
+  <div class="container">
+    {#if crumblePath}
+      <div class="crumble-path">
+        {@render crumblePath()}
+      </div>
+    {/if}
+    
+    <form 
+      method="POST" 
+      action="?/toggleScaling" 
+      use:enhance={({ formData, cancel }) => {
+        const newValue = formData.get('scalingEnabled') === 'on';
+        scalingEnabled = newValue;
+        onchange?.(newValue);
+        
+        return async ({ result }) => {
+          if (result.type === 'success') {
+            // Force page reload to apply scaling changes
+            window.location.reload();
+          }
+        };
+      }}
+    >
+      <label class="scaling-toggle">
+        <input 
+          type="checkbox" 
+          name="scalingEnabled" 
+          bind:checked={scalingEnabled}
+          onchange={(e) => /** @type {HTMLInputElement} */ (e.target).form.requestSubmit()}
+        />
+        <span class="type-ui-sm">Enable Design Scaling</span>
+      </label>
+    </form>
+  </div>
+</div>
+
+<style src="./topbar.css">@reference '../../../../app.css';
+
+[data-component="top-bar"] {
+  @apply bg-surface-100 border-surface-300 sticky top-0 z-10;
+  @apply p-8ht;
+  
+  & .container {
+    @apply max-w-screen-xl mx-auto flex justify-between items-center;
+  }
+  
+  & .scaling-toggle {
+    @apply flex items-center cursor-pointer;
+    @apply gap-8bt;
+    
+    & input[type="checkbox"] {
+      @apply accent-primary-500;
+    }
+  }
+
+  & .crumble-path {
+    @apply flex items-center;
+  }
+}
+
+/* Dark mode support */
+@media (prefers-color-scheme: dark) {
+  [data-component="top-bar"] {
+    @apply bg-surface-800 border-surface-600;
+  }
+}</style>

package/dist/ui/dev/explorer/TopBar.svelte.d.ts

@@ -0,0 +1,14 @@
+export default TopBar;
+type TopBar = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<{
+        scalingEnabled: boolean;
+        onchange?: (enabled: boolean) => void;
+        crumblePath?: Snippet<[]>;
+    }>): void;
+};
+declare const TopBar: import("svelte").Component<{
+    scalingEnabled: boolean;
+    onchange?: (enabled: boolean) => void;
+    crumblePath?: import("svelte").Snippet;
+}, {}, "scalingEnabled">;

package/dist/ui/dev/explorer/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Explorer } from "./Explorer.svelte";
+export { default as TopBar } from "./TopBar.svelte";

package/dist/ui/dev/explorer/index.js

@@ -0,0 +1,8 @@
+/**
+ * Dev explorer components
+ * @fileoverview Reusable components for navigating nested folder
+ * structures with dynamic routing support
+ */
+
+export { default as Explorer } from './Explorer.svelte';
+export { default as TopBar } from './TopBar.svelte';

package/dist/ui/dev/explorer/topbar.css

@@ -0,0 +1,30 @@
+@reference '../../../../app.css';
+
+[data-component="top-bar"] {
+  @apply bg-surface-100 border-surface-300 sticky top-0 z-10;
+  @apply p-8ht;
+  
+  & .container {
+    @apply max-w-screen-xl mx-auto flex justify-between items-center;
+  }
+  
+  & .scaling-toggle {
+    @apply flex items-center cursor-pointer;
+    @apply gap-8bt;
+    
+    & input[type="checkbox"] {
+      @apply accent-primary-500;
+    }
+  }
+
+  & .crumble-path {
+    @apply flex items-center;
+  }
+}
+
+/* Dark mode support */
+@media (prefers-color-scheme: dark) {
+  [data-component="top-bar"] {
+    @apply bg-surface-800 border-surface-600;
+  }
+}

package/package.json

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