@hkdigital/lib-core 0.3.10 → 0.3.12

package/dist/design/README.md

@@ -0,0 +1,405 @@
+# HKdigital Design System
+
+A comprehensive, responsive design system built for SvelteKit applications. This system provides consistent scaling, typography, spacing, and theming across all screen sizes using CSS custom properties and Tailwind CSS.
+
+## Quick Start
+
+### Basic Usage
+
+```javascript
+// tailwind.config.js
+import { 
+  spacing, 
+  fontSize, 
+  borderRadius, 
+  customUtilitiesPlugin 
+} from '@hkdigital/lib-core/design/index.js';
+
+export default {
+  theme: {
+    extend: {
+      spacing,
+      fontSize,
+      borderRadius
+    }
+  },
+  plugins: [
+    customUtilitiesPlugin
+  ]
+};
+```
+
+```svelte
+<!-- +layout.svelte -->
+<script>
+  import { DESIGN, CLAMPING, rootDesignVarsHTML } from '@hkdigital/lib-core/design';
+</script>
+
+<svelte:head>
+  {@html rootDesignVarsHTML(DESIGN, CLAMPING)}
+</svelte:head>
+
+{@render children()}
+```
+
+## Core Concepts
+
+### Responsive Scaling System
+
+The design system is built around a **1024×768 design reference** that automatically scales to any screen size with sensible minimum and maximum bounds.
+
+#### CSS Variables Created:
+- `--scale-ui`: Clamped UI scaling (0.3× to 2×)
+- `--scale-text-base`: Base text scaling (0.75× to 1.5×)
+- `--scale-text-heading`: Heading text scaling (0.75× to 2.25×)
+- `--scale-text-ui`: UI text scaling (0.5× to 1.25×)
+
+## Spacing Classes
+
+### UI Points
+**Primary method for UI element spacing:**
+
+```html
+<div class="p-20up m-10up">
+  <!-- 20px padding, 10px margin at design size -->
+  <!-- Automatically scales with viewport -->
+</div>
+```
+
+Available: `1up`, `2up`, `4up`, `5up`, `6up`, `10up`, `20up`, `30up`, `40up`, `50up`, `60up`, `70up`, `80up`, `90up`, `100up`, `120up`, `140up`, `160up`, `180up`, `200up`
+
+### Text-Based Spacing
+**For spacing relative to text size:**
+
+```html
+<div class="mb-16bt">     <!-- Base text spacing -->
+<div class="p-12ut">      <!-- UI text spacing -->
+<div class="mt-24ht">     <!-- Heading text spacing -->
+```
+
+Available for all text point sizes: `1ut/bt/ht`, `2ut/bt/ht`, `4ut/bt/ht`, `6ut/bt/ht`, `8ut/bt/ht`, `10ut/bt/ht`, `11ut/bt/ht`, `12ut/bt/ht`, `16ut/bt/ht`, `20ut/bt/ht`, `24ut/bt/ht`, `28ut/bt/ht`, `32ut/bt/ht`, `36ut/bt/ht`, `50ut/bt/ht`
+
+### Alternative Viewport Units
+```html
+<div class="w-100wp h-50hp">  <!-- Width/height points -->
+```
+
+## Typography Classes
+
+### Complete Typography Styles
+**Use `type-` classes for complete text styling:**
+
+```html
+<h1 class="type-heading-h1">Main Title</h1>
+<h2 class="type-heading-h2">Section Title</h2>
+<h3 class="type-heading-h3">Subsection</h3>
+<p class="type-base-md">Body paragraph text</p>
+<span class="type-ui-sm">Interface text</span>
+
+<!-- Dark mode variants -->
+<h1 class="type-heading-h1-dark">Dark mode title</h1>
+<p class="type-base-md-dark">Dark mode paragraph</p>
+```
+
+**Available Typography Classes:**
+- **Headings**: `type-heading-h1`, `type-heading-h2`, `type-heading-h3`, `type-heading-h4`, `type-heading-h5`
+- **Body Text**: `type-base-sm`, `type-base-md`, `type-base-lg`
+- **UI Text**: `type-ui-sm`, `type-ui-md`, `type-ui-lg`
+- **Dark Variants**: Add `-dark` suffix to any class
+
+### Font Size Only
+**Use `text-` classes for font size only:**
+
+```html
+<p class="text-base-md">16px scaled base text</p>
+<h2 class="text-heading-h2">28px scaled heading</h2>
+```
+
+## Border & Radius Classes
+
+### Border Radius
+```html
+<div class="rounded-xs">    <!-- 5px scaled -->
+<div class="rounded-sm">    <!-- 10px scaled -->
+<div class="rounded-md">    <!-- 25px scaled -->
+<div class="rounded-lg">    <!-- 35px scaled -->
+<div class="rounded-none">  <!-- 0px -->
+<div class="rounded-full">  <!-- 9999px -->
+```
+
+### Border & Stroke Width
+```html
+<div class="border-width-thin">    <!-- 1px scaled -->
+<div class="border-width-normal">  <!-- 2px scaled -->
+<div class="border-width-thick">   <!-- 4px scaled -->
+
+<svg class="stroke-normal">        <!-- 2px scaled stroke -->
+<div class="outline-thick">        <!-- 4px scaled outline -->
+```
+
+## Colors (Theme hkdev)
+
+### Brand Colors
+```html
+<div class="bg-primary-500 text-primary-contrast-500">
+<div class="bg-secondary-600 text-secondary-contrast-600">
+<div class="bg-tertiary-400 text-tertiary-contrast-400">
+```
+
+### Surface Colors (Neutrals)
+```html
+<div class="bg-surface-50">   <!-- Lightest -->
+<div class="bg-surface-500">  <!-- Medium -->
+<div class="bg-surface-950">  <!-- Darkest -->
+```
+
+### Status Colors
+```html
+<div class="bg-success-500 text-success-contrast-500">
+<div class="bg-warning-500 text-warning-contrast-500">
+<div class="bg-error-500 text-error-contrast-500">
+```
+
+**Auto Contrast**: Each color includes automatic contrast colors for accessibility. Use `text-{color}-contrast-{shade}` for optimal readability.
+
+## Component Styling
+
+Components use `data-` attributes with CSS custom properties:
+
+```html
+<button data-component="button" data-role="primary">
+  Primary Button
+</button>
+
+<button data-component="button" data-role="secondary">
+  Secondary Button
+</button>
+```
+
+## Utility Functions
+
+### CSS Variable Utilities
+
+```javascript
+import { 
+  getRootCssDesignWidth,
+  getRootCssDesignHeight,
+  getAllRootScalingVars
+} from '@hkdigital/lib-core/design';
+
+// Get current design dimensions
+const designWidth = getRootCssDesignWidth();   // 1024
+const designHeight = getRootCssDesignHeight(); // 768
+
+// Get all current scaling factors
+const scales = getAllRootScalingVars();
+// Returns: { scaleW, scaleH, scaleViewport, scaleUI, scaleTextBase, scaleTextHeading, scaleTextUI }
+```
+
+### Clamp Utilities
+
+```javascript
+import { clamp, getClampParams } from '@hkdigital/lib-core/design';
+
+// Mathematical clamp function
+const value = clamp(0.5, 0.3, 2.0); // Returns 0.5 (clamped between 0.5 and 2.0)
+
+// Extract clamp parameters from CSS variables
+const params = getClampParams('scale-ui');
+// Returns: { min: 0.3, max: 2.0 }
+```
+
+### Component State Classes
+
+```javascript
+import { toStateClasses } from '@hkdigital/lib-core/design';
+
+// Generate state classes from object
+const classes = toStateClasses({
+  selected: true,
+  loading: false,
+  error: true,
+  disabled: false
+});
+// Returns: "state-selected state-error"
+```
+
+```html
+<!-- Usage in components -->
+<button class={toStateClasses({ selected, disabled, loading })}>
+  Button Text
+</button>
+```
+
+### Responsive Scaling
+
+#### Viewport-Based Scaling
+
+```javascript
+import { enableScalingUI } from '@hkdigital/lib-core/design';
+
+// Enable automatic viewport scaling
+const cleanup = enableScalingUI(DESIGN, CLAMPING);
+
+// Call cleanup when component is destroyed
+onDestroy(cleanup);
+```
+
+#### Container-Based Scaling
+
+```javascript
+import { enableContainerScaling } from '@hkdigital/lib-core/design';
+
+let containerElement;
+
+// Enable scaling for specific container
+const cleanup = enableContainerScaling({
+  container: containerElement,
+  design: DESIGN,
+  clamping: CLAMPING,
+  useResizeObserver: true
+});
+
+// Optional custom dimension getter
+const cleanupCustom = enableContainerScaling({
+  container: containerElement,
+  design: DESIGN,
+  clamping: CLAMPING,
+  getDimensions: () => ({ width: 800, height: 600 })
+});
+```
+
+```svelte
+<!-- Svelte component example -->
+<script>
+  import { onMount, onDestroy } from 'svelte';
+  import { enableContainerScaling, DESIGN, CLAMPING } from '@hkdigital/lib-core/design';
+  
+  let containerElement;
+  let cleanup;
+  
+  onMount(() => {
+    cleanup = enableContainerScaling({
+      container: containerElement,
+      design: DESIGN,
+      clamping: CLAMPING
+    });
+  });
+  
+  onDestroy(() => {
+    cleanup?.();
+  });
+</script>
+
+<div bind:this={containerElement} class="scaled-container">
+  <!-- Content that scales with container -->
+  <div class="p-20up text-base-md">Responsive content</div>
+</div>
+```
+
+## Advanced Usage
+
+### Custom Design Configuration
+
+```javascript
+// your-project/src/lib/design/design-config.js
+import { 
+  generateTextBasedSpacing,
+  generateTextStyles 
+} from '@hkdigital/lib-core/design';
+
+// Custom design dimensions
+export const CUSTOM_DESIGN = {
+  width: 1440,
+  height: 900
+};
+
+// Custom text sizes
+export const CUSTOM_TEXT_SIZES = {
+  sm: { size: 12, lineHeight: 1.4 },
+  md: { size: 16, lineHeight: 1.4 },
+  lg: { size: 20, lineHeight: 1.4 }
+};
+
+// Generate custom extensions
+export const customSpacing = generateTextBasedSpacing([8, 12, 16, 24, 32]);
+export const customFontSize = generateTextStyles(CUSTOM_TEXT_SIZES, 'base');
+```
+
+### Available Generator Functions
+
+```javascript
+import {
+  generateTextBasedSpacing,      // ut/bt/ht spacing units
+  generateViewportBasedSpacing,  // up/wp/hp spacing units
+  generateTextStyles,            // Complete typography styles
+  generateBorderRadiusStyles,    // Border radius with scaling
+  generateWidthStyles            // Border/stroke width with scaling
+} from '@hkdigital/lib-core/design';
+```
+
+### Configuration Objects
+
+All configuration objects are exported for customization:
+
+```javascript
+import {
+  DESIGN,                 // { width: 1024, height: 768 }
+  CLAMPING,              // Min/max scale bounds
+  TEXT_POINT_SIZES,      // [1, 2, 4, 6, 8, 10, ...]
+  VIEWPORT_POINT_SIZES,  // [1, 2, 4, 5, 6, 10, ...]
+  TEXT_BASE_SIZES,       // { sm: {...}, md: {...}, lg: {...} }
+  TEXT_HEADING_SIZES,    // { h1: {...}, h2: {...}, ... }
+  TEXT_UI_SIZES,         // { sm: {...}, md: {...}, lg: {...} }
+  RADIUS_SIZES,          // Border radius configurations
+  BORDER_WIDTH_SIZES,    // Border width configurations
+  STROKE_WIDTH_SIZES     // Stroke width configurations
+} from '@hkdigital/lib-core/design';
+```
+
+## Best practices
+
+### Do's ✅
+- Use `up` units for UI spacing: `p-20up`, `m-10up`
+- Use `type-` classes for complete typography: `type-base-md`
+- Use `ut/bt/ht` for text-related spacing: `mb-16bt`
+- Use contrast colors for accessibility: `text-primary-contrast-500`
+- Test across multiple screen sizes
+
+### Don'ts ❌
+- Don't use hardcoded pixel values: `p-4` → use `p-4up`
+- Don't forget dark mode variants: add `-dark` classes
+- Don't use `text-` classes when you need complete typography styling
+
+## Themes
+
+The system includes the complete **theme hkdev** with:
+- Color palette (primary, secondary, tertiary, status, surface)
+- Component styles (buttons, panels, inputs, etc.)
+- Typography settings (fonts, weights, spacing)
+- Responsive behavior
+
+Themes are public and can be extended or customized by other projects.
+
+## Browser Support
+
+- Modern browsers with CSS custom properties support
+- CSS `clamp()` function support
+- Viewport units (`vw`, `vh`) support
+
+## Migration Guide
+
+If migrating from the old structure:
+
+```javascript
+// OLD
+import { DESIGN } from '$lib/design/design-config.js';
+import { customUtilitiesPlugin } from '$lib/design/skeleton.js';
+
+// NEW
+import { DESIGN, customUtilitiesPlugin } from '@hkdigital/lib-core/design';
+```
+
+---
+
+For more examples and advanced usage, see the `/examples` routes in this library.

package/dist/design/index.d.ts

@@ -0,0 +1,8 @@
+export { customUtilitiesPlugin } from "./plugins/skeleton.js";
+export { toStateClasses } from "./utils/states.js";
+export { DESIGN, CLAMPING, TEXT_POINT_SIZES, VIEWPORT_POINT_SIZES, TEXT_BASE_SIZES, TEXT_HEADING_SIZES, TEXT_UI_SIZES, RADIUS_SIZES, BORDER_WIDTH_SIZES, STROKE_WIDTH_SIZES } from "./config/design-config.js";
+export { generateTextBasedSpacing, generateViewportBasedSpacing, generateTextStyles, generateBorderRadiusStyles, generateWidthStyles } from "./generators/index.js";
+export { spacing, fontSize, borderRadius, borderWidth, strokeWidth, outlineWidth, outlineOffset } from "./tailwind-theme-extend.js";
+export { rootDesignVarsHTML, getRootCssDesignWidth, getRootCssDesignHeight, getAllRootScalingVars } from "./utils/root-vars.js";
+export { getClampParams, clamp } from "./utils/clamp.js";
+export { enableContainerScaling, enableScalingUI } from "./utils/scaling.js";

package/dist/design/index.js

@@ -0,0 +1,97 @@
+/**
+ * @fileoverview HKdigital Core Design System
+ * 
+ * This module provides a comprehensive design system for building consistent,
+ * responsive interfaces. It includes configuration objects, generator functions,
+ * and ready-to-use Tailwind theme extensions.
+ * 
+ * @example Basic usage in tailwind.config.js
+ * ```javascript
+ * import { spacing, fontSize, customUtilitiesPlugin } from '@hkdigital/lib-core/design';
+ * 
+ * export default {
+ *   theme: {
+ *     extend: { spacing, fontSize }
+ *   },
+ *   plugins: [customUtilitiesPlugin]
+ * };
+ * ```
+ * 
+ * @example Advanced customization
+ * ```javascript
+ * import { 
+ *   generateTextBasedSpacing, 
+ *   DESIGN, 
+ *   TEXT_POINT_SIZES 
+ * } from '@hkdigital/lib-core/design';
+ * 
+ * const customSpacing = generateTextBasedSpacing([8, 12, 16, 24]);
+ * ```
+ */
+
+// === Configuration Objects ===
+// Projects can import and customize these for their own design systems
+
+export {
+  DESIGN,
+  CLAMPING,
+  TEXT_POINT_SIZES,
+  VIEWPORT_POINT_SIZES,
+  TEXT_BASE_SIZES,
+  TEXT_HEADING_SIZES,
+  TEXT_UI_SIZES,
+  RADIUS_SIZES,
+  BORDER_WIDTH_SIZES,
+  STROKE_WIDTH_SIZES
+} from './config/design-config.js';
+
+// === Generator Functions ===
+// Essential tools for projects to build custom Tailwind extensions
+
+export {
+  generateTextBasedSpacing,
+  generateViewportBasedSpacing,
+  generateTextStyles,
+  generateBorderRadiusStyles,
+  generateWidthStyles
+} from './generators/index.js';
+
+// === Ready-to-use Tailwind Extensions ===
+// Built using default configuration - projects can use directly or as reference
+
+export {
+  spacing,
+  fontSize,
+  borderRadius,
+  borderWidth,
+  strokeWidth,
+  outlineWidth,
+  outlineOffset
+} from './tailwind-theme-extend.js';
+
+// === Plugins & Utilities ===
+// Framework integration tools
+
+export { customUtilitiesPlugin } from './plugins/skeleton.js';
+
+// === Utilities ===
+// Essential utility functions for design system implementation
+
+export { 
+  rootDesignVarsHTML,
+  getRootCssDesignWidth,
+  getRootCssDesignHeight,
+  getAllRootScalingVars
+} from './utils/root-vars.js';
+
+export { 
+  getClampParams,
+  clamp
+} from './utils/clamp.js';
+
+export { toStateClasses } from './utils/states.js';
+
+export {
+  enableContainerScaling,
+  enableScalingUI
+} from './utils/scaling.js';

package/dist/design/tailwind-theme-extend.js

@@ -16,10 +16,10 @@
  *   let { children } = $props();
  *
  *   import { DESIGN, CLAMPING }
- *     from './design-config.js';
+ *     from './config/design-config.js';
  *
  *   import { rootDesignVarsHTML }
- *     from '@hkdigital/lib-sveltekit/util/design-system/index.js';
+ *     from '@hkdigital/lib-core/design/utils/root-vars.js';
  * </script>
  *
  * <svelte:head>
@@ -93,7 +93,7 @@ import {
   generateTextStyles,
   generateBorderRadiusStyles,
   generateWidthStyles
-} from '../util/design-system/tailwind.js';
+} from './generators/index.js';
 
 import {
   TEXT_POINT_SIZES,
@@ -104,7 +104,7 @@ import {
   RADIUS_SIZES,
   BORDER_WIDTH_SIZES,
   STROKE_WIDTH_SIZES
-} from './design-config.js';
+} from './config/design-config.js';
 
 /* == Internals */
 

package/dist/design/themes/README.md

@@ -0,0 +1,103 @@
+# Themes
+
+This folder contains theme configurations for the SvelteKit library, built on top of Skeleton.dev's theming system.
+
+## Current Themes
+
+### hkdev
+The main theme for this project, containing:
+- `theme.css` - Skeleton.dev generated theme file with CSS custom properties
+- `globals.css` - Global styles and utilities
+- `components.css` - Component-specific styles
+- `responsive.css` - Responsive design adjustments
+- `debug.css` - Debug styles for development (commented out by default)
+
+## How to Use Themes
+
+Themes are imported and configured in `src/app.css`. The current setup imports the hkdev theme:
+
+```css
+/* Import theme classes and styles */
+@import './lib/themes/hkdev/theme.css' layer(theme);
+
+/* Import additional theme files */
+@import '$lib/design/themes/hkdev/globals.css';
+@import '$lib/design/themes/hkdev/components.css' layer(components);
+@import '$lib/design/themes/hkdev/responsive.css';
+```
+
+### Applying Themes
+
+To activate a theme, set the `data-theme` attribute on your HTML element:
+
+```html
+<html data-theme="hkdev">
+```
+
+Or dynamically with JavaScript:
+```javascript
+document.documentElement.setAttribute('data-theme', 'hkdev');
+```
+
+## Creating New Themes
+
+### Using Skeleton.dev Theme Generator
+
+1. **Visit the Theme Generator**: Go to [themes.skeleton.dev/themes/create](https://themes.skeleton.dev/themes/create)
+
+2. **Customize Your Theme**:
+   - Choose color palettes
+   - Set font styles for base text, headings, and anchors
+   - Configure background options
+   - Preview changes in real-time
+
+3. **Generate and Download**:
+   - The generator creates a CSS file with CSS custom properties
+   - Download the generated `theme.css` file
+
+4. **Integration Steps**:
+   - Create a new folder in `src/lib/design/themes/[your-theme-name]/`
+   - Place the downloaded `theme.css` file in the new folder
+   - Create additional files as needed:
+     - `globals.css` - Global styles
+     - `components.css` - Component styles
+     - `responsive.css` - Responsive adjustments
+   - Update `src/app.css` to import your new theme files
+
+### Theme Structure
+
+Each theme folder should follow this structure:
+```
+themes/
+└── [theme-name]/
+    ├── theme.css          # Skeleton.dev generated theme
+    ├── globals.css        # Global styles and utilities
+    ├── components.css     # Component-specific styles
+    ├── responsive.css     # Responsive design rules
+    └── components/        # Individual component styles
+        ├── buttons/
+        ├── inputs/
+        ├── panels/
+        └── ...
+```
+
+## Theme System Features
+
+- **CSS Custom Properties**: Themes use CSS variables for easy customization
+- **Layer Support**: Organized with CSS layers (theme, base, components, utilities)
+- **Light/Dark Mode**: Automatic support for light and dark variants
+- **Component Isolation**: Individual component styles in separate files
+- **Responsive Design**: Mobile-first responsive adjustments
+
+## Documentation
+
+For more information about Skeleton.dev themes:
+- [Skeleton.dev Theme Documentation](https://www.skeleton.dev/docs/design/themes)
+- [Theme Generator](https://themes.skeleton.dev/themes/create)
+- [Skeleton.dev GitHub](https://github.com/skeletonlabs/skeleton)
+
+## Notes
+
+- The theme generator is not available for small screens - use a tablet or desktop
+- Themes can be imported and modified for advanced customization
+- All themes should be compatible with Skeleton.dev v3 components

package/dist/{themes → design/themes}/hkdev/theme-ext.js

@@ -1,4 +1,4 @@
-import { theme as themeStore } from '../../stores/index.js';
+import { theme as themeStore } from '../../../stores/index.js';
 
 /**
  * Set meta them color for the current theme

package/dist/{util/design-system/css → design/utils}/clamp.js

@@ -1,4 +1,4 @@
-import { getRootCssVar } from '../../css/index.js';
+import { getRootCssVar } from '../../util/css/index.js';
 
 /**
  * Cache to that ensures we parse CSS clamp parameters only once

package/dist/{util/design-system/css/root-design-vars.d.ts → design/utils/root-vars.d.ts}

@@ -24,9 +24,9 @@
  * @example
  * // +layout.svelte
  * <script>
- * import { DESIGN, CLAMPING } from '../../../tailwind/extend/clamping/config.js';
+ * import { DESIGN, CLAMPING } from '../config/design-config.js';
  *
- * import { rootDesignVarsHTML } from '../index.js';
+ * import { rootDesignVarsHTML } from './root-vars.js';
  * </script>
  *
  * <svelte:head>

package/dist/{util/design-system/css/root-design-vars.js → design/utils/root-vars.js}

@@ -1,4 +1,4 @@
-import { getRootCssVar } from '../../css/css-vars.js';
+import { getRootCssVar } from '../../util/css/css-vars.js';
 
 /**
  * Generates a complete HTML style tag with CSS custom properties for
@@ -26,9 +26,9 @@ import { getRootCssVar } from '../../css/css-vars.js';
  * @example
  * // +layout.svelte
  * <script>
- * import { DESIGN, CLAMPING } from '../../../tailwind/extend/clamping/config.js';
+ * import { DESIGN, CLAMPING } from '../config/design-config.js';
  *
- * import { rootDesignVarsHTML } from '../index.js';
+ * import { rootDesignVarsHTML } from './root-vars.js';
  * </script>
  *
  * <svelte:head>

package/dist/{util/design-system/layout → design/utils}/scaling.js

@@ -1,4 +1,4 @@
-import { clamp } from '../css/clamp.js';
+import { clamp } from './clamp.js';
 
 /**
  * Manages responsive design scaling by calculating and applying scale factors