@hkdigital/lib-core 0.3.11 → 0.3.13

package/dist/ui/primitives/layout/grid-layers/GridLayers.svelte

@@ -1,63 +1,63 @@
-<script>
-  /**
-   * GridLayers Component
-   *
-   * Creates a single-cell grid where all children occupy the same space,
-   * enabling layered layouts with natural height behavior.
-   *
-   * @type {{
-   *   base?: string,
-   *   bg?: string,
-   *   padding?: string,
-   *   margin?: string,
-   *   classes?: string,
-   *   style?: string,
-   *   overflow?: string,
-   *   children: import('svelte').Snippet,
-   *   [attr: string]: any
-   * }}
-   */
-  const {
-    // Container styles
-    base = '',
-    bg = '',
-    padding = '',
-    margin = '',
-    classes = '',
-    style = '',
-    overflow = '',
-
-    // Content
-    children,
-
-    // Attributes
-    ...attrs
-  } = $props();
-
-  // Build the inline style
-  let containerStyle = $derived.by(() => {
-    const styles = ['grid-template: 1fr / 1fr;'];
-
-    if (style) {
-      styles.push(style);
-    }
-
-    return styles.join(' ');
-  });
-</script>
-
-<div
-  data-component="grid-layers"
-  class="grid {base} {bg} {classes} {margin} {padding} {overflow}"
-  style={containerStyle}
-  {...attrs}
->
-  {@render children()}
-</div>
-
-<style>
-  /* All direct children occupy the same grid area */
-  div > :global(*) {
-    grid-area: 1 / 1;
-  }
-</style>
+<script>
+  /**
+   * GridLayers Component
+   *
+   * Creates a single-cell grid where all children occupy the same space,
+   * enabling layered layouts with natural height behavior.
+   *
+   * @type {{
+   *   base?: string,
+   *   bg?: string,
+   *   padding?: string,
+   *   margin?: string,
+   *   classes?: string,
+   *   style?: string,
+   *   overflow?: string,
+   *   children: import('svelte').Snippet,
+   *   [attr: string]: any
+   * }}
+   */
+  const {
+    // Container styles
+    base = '',
+    bg = '',
+    padding = '',
+    margin = '',
+    classes = '',
+    style = '',
+    overflow = '',
+
+    // Content
+    children,
+
+    // Attributes
+    ...attrs
+  } = $props();
+
+  // Build the inline style
+  let containerStyle = $derived.by(() => {
+    const styles = ['grid-template: 1fr / 1fr;'];
+
+    if (style) {
+      styles.push(style);
+    }
+
+    return styles.join(' ');
+  });
+</script>
+
+<div
+  data-component="grid-layers"
+  class="grid {base} {bg} {classes} {margin} {padding} {overflow}"
+  style={containerStyle}
+  {...attrs}
+>
+  {@render children()}
+</div>
+
+<style>
+  /* All direct children occupy the same grid area */
+  div > :global(*) {
+    grid-area: 1 / 1;
+  }
+</style>

package/dist/ui/primitives/layout/grid-layers/GridLayers.svelte__heightFrom__

@@ -0,0 +1,372 @@
+<script>
+  import { onMount, onDestroy } from 'svelte';
+  import { setupLayerObserver, measureTargetLayer } from './util.js';
+
+  /**
+   * # GridLayers Component
+   *
+   * A Svelte 5 component that creates a layered grid layout where all
+   * children occupy the same grid area, allowing for overlapping content with
+   * precise positioning control.
+   *
+   * ## Overview
+   *
+   * GridLayers uses CSS Grid to stack multiple elements in the same grid cell
+   * (1x1 grid), enabling layered layouts without absolute positioning on the
+   * children. This approach maintains the natural flow and sizing behavior of
+   * grid items while allowing them to overlap.
+   *
+   * ## Height Control
+   *
+   * The component offers two methods for controlling height:
+   *
+   * ### 1. Fixed Height (default)
+   *
+   * Use the `height` prop with Tailwind classes:
+   * ```svelte
+   * <GridLayers height="h-[500px]">
+   *    <!-- content -->
+   * </GridLayers>
+   * ```
+   *
+   * ### 2. Dynamic Height
+   * Use the `heightFrom` prop to make the container's height match a specific
+   * child layer:
+   *
+   * ```svelte
+   * <GridLayers heightFrom="content">
+   *   <div data-layer="content">
+   *     <!-- This layer's height determines the container height -->
+   *   </div>
+   *   <div data-layer="overlay">
+   *     <!-- Other layers adapt to the container -->
+   *   </div>
+   * </GridLayers>
+   * ```
+   *
+   * The `heightFrom` value should match a child's `data-layer` attribute.
+   * The component will:
+   *    - Initially render invisibly to measure the target layer
+   *    - Apply the measured height to the container
+   *    - Watch for changes and update automatically
+   *
+   * ## Positioning Layers
+   *
+   * Each child element can be positioned within the grid cell using Tailwind's
+   * alignment utilities:
+   *
+   * ### justify-self (Horizontal Alignment)
+   *   - `justify-self-start` - Align to the left
+   *   - `justify-self-center` - Center horizontally
+   *   - `justify-self-end` - Align to the right
+   *   - `justify-self-stretch` - Stretch to full width (default)
+   *
+   * ### self (Vertical Alignment)
+   *   - `self-start` - Align to the top
+   *   - `self-center` - Center vertically
+   *   - `self-end` - Align to the bottom
+   *   - `self-stretch` - Stretch to full height (default)
+   *
+   * ### Combining Positions
+   * ```svelte
+   * <GridLayers height="h-[400px]">
+   *   <div class="justify-self-start self-start">Top Left</div>
+   *     <div class="justify-self-center self-center">Centered</div>
+   *     <div class="justify-self-end self-end">Bottom Right</div>
+   * </GridLayers>
+   * ```
+   *
+   * ### Fine-tuning with Margins
+   * For precise positioning adjustments, use margins:
+   * ```svelte
+   * <div class="justify-self-end self-end mr-4 mb-4">
+   *   <!-- Positioned at bottom-right with 1rem spacing -->
+   * </div>
+   * ```
+   *
+   * ## Technical Implementation
+   *
+   * ### The Grid Container
+   * The inner grid container uses `absolute inset-0` which:
+   *   - Positions it absolutely within the relative parent
+   *   - `inset-0` is shorthand for `top: 0, right: 0, bottom: 0, left: 0`
+   *   - Makes the grid fill the entire parent container
+   *   - Ensures the grid respects the parent's dimensions (fixed or dynamic)
+   *
+   * This approach creates a stable positioning context while maintaining the
+   * parent's flow in the document.
+   *
+   *    ### Grid Structure
+   *    All children are assigned to the same grid cell:
+   *    ```css
+   *    grid-template-columns: 1fr;
+   *    grid-template-rows: 1fr;
+   *    grid-column: 1;
+   *    grid-row: 1;
+   *    ```
+   *
+   *    ## Overflow Behavior
+   *
+   *    When a layer's content exceeds the container bounds:
+   *
+   *    ### Default Behavior
+   *    - Content will overflow and be visible outside the container
+   *    - This can break layouts or create unwanted scrollbars
+   *
+   *    ### Controlling Overflow
+   *    Add overflow utilities to the container:
+   *    ```svelte
+   *    <!-- Hide overflow -->
+   *    <GridLayers classes="overflow-hidden">
+   *
+   *    <!-- Scroll if needed -->
+   *    <GridLayers classes="overflow-auto">
+   *
+   *    <!-- Scroll specific layer -->
+   *    <GridLayers>
+   *      <div class="overflow-auto">
+   *        <!-- Scrollable content -->
+   *      </div>
+   *    </GridLayers>
+   *    ```
+   *
+   *    ### Best Practices for Overflow
+   *    1. Use `overflow-hidden` on the container when layers should be clipped
+   *    2. Apply `overflow-auto` to specific layers that need scrolling
+   *    3. Consider using `max-h-*` classes on content layers
+   *    4. Test with different content sizes to ensure proper behavior
+   *
+   *    ## Z-Index Stacking
+   *
+   *    Layers have a base `z-index: 0` and stack in DOM order. Control stacking with:
+   *    ```svelte
+   *    <div class="z-10">Top layer</div>
+   *    <div class="z-0">Base layer</div>
+   *    <div class="z-20">Topmost layer</div>
+   *    ```
+   *
+   *    ## Common Patterns
+   *
+   *    ### Header/Content/Footer
+   *    ```svelte
+   *    <GridLayers heightFrom="content">
+   *      <div data-layer="header" class="self-start">
+   *        <header>Fixed header</header>
+   *      </div>
+   *      <div data-layer="content" class="self-center">
+   *        <main>Dynamic content</main>
+   *      </div>
+   *      <div data-layer="footer" class="self-end">
+   *        <footer>Fixed footer</footer>
+   *      </div>
+   *    </GridLayers>
+   *    ```
+   *
+   *    ### Centered Overlay
+   *    ```svelte
+   *    <GridLayers height="h-screen">
+   *      <div class="z-0">
+   *        <img src="background.jpg" class="w-full h-full object-cover" />
+   *      </div>
+   *      <div class="z-10 justify-self-center self-center">
+   *        <div class="bg-white p-8 rounded shadow-lg">
+   *          Centered content over background
+   *        </div>
+   *      </div>
+   *    </GridLayers>
+   *    ```
+   *
+   *    ### Corner Badges
+   *    ```svelte
+   *    <GridLayers height="h-64">
+   *      <div class="justify-self-end self-start m-4 z-10">
+   *        <span class="badge">New</span>
+   *      </div>
+   *      <div>
+   *        Main content
+   *      </div>
+   *    </GridLayers>
+   *    ```
+   */
+
+  /**
+   * @type {{
+   *   base?: string,
+   *   bg?: string,
+   *   padding?: string,
+   *   margin?: string,
+   *   height?: string,
+   *   classes?: string,
+   *   style?: string,
+   *   cellBase?: string,
+   *   cellBg?: string,
+   *   cellPadding?: string,
+   *   cellMargin?: string,
+   *   cellClasses?: string,
+   *   cellStyle?: string,
+   *   heightFrom?: string|null,
+   *   children: import('svelte').Snippet,
+   *   cellAttrs?: { [attr: string]: any },
+   *   [attr: string]: any
+   * }}
+   */
+  const {
+    // Style
+    base = '',
+    bg = '',
+    padding = '',
+    margin = '',
+    height = 'h-full',
+    classes = '',
+    style = '',
+    cellBase = '',
+    cellBg = '',
+    cellPadding = '',
+    cellMargin = '',
+    cellClasses = '',
+    cellStyle = '',
+
+    // Behavior
+    heightFrom = null,
+
+    // Props
+    cellAttrs = {},
+    children,
+
+    // Attributes
+    ...attrs
+  } = $props();
+
+  // Component state
+  let gridContent = $state(null);
+  let calculatedHeight = $state(0);
+  let observer = $state(null);
+
+  // Start with true if heightFrom is provided
+  let isFirstRender = $state(heightFrom !== null);
+
+  let preCalculatedHeight = $state(0);
+
+  // Derived container style that updates reactively when dependencies change
+  let containerStyle = $derived.by(() => {
+    const styles = [];
+
+    if (style) {
+      styles.push(style);
+    }
+
+    if (heightFrom && calculatedHeight > 0) {
+      styles.push(`height: ${calculatedHeight}px;`);
+    }
+
+    return styles.join(' ');
+  });
+
+  /**
+   * Handler for height changes detected by the observer
+   * @param {number} newHeight - The new calculated height
+   */
+  function handleHeightChange(newHeight) {
+    calculatedHeight = newHeight;
+  }
+
+  /**
+   * Initialize height measurement and observation
+   */
+  function initializeHeightTracking() {
+    if (!heightFrom || !gridContent) return;
+
+    // Measure the layer initially
+    const { element, height } = measureTargetLayer(gridContent, heightFrom);
+
+    if (element) {
+      calculatedHeight = height;
+
+      // Setup observer for future changes
+      observer = setupLayerObserver(element, handleHeightChange);
+    }
+  }
+
+  // Initialize on mount with the two-pass rendering approach
+  onMount(() => {
+    if (heightFrom) {
+      // First render: measure invisibly
+      requestAnimationFrame(() => {
+        if (gridContent) {
+          const { element, height } = measureTargetLayer(gridContent, heightFrom);
+
+          if (element) {
+            preCalculatedHeight = height;
+
+            // Second render: show with correct height
+            requestAnimationFrame(() => {
+              calculatedHeight = preCalculatedHeight;
+              isFirstRender = false;
+
+              // Setup observer for future changes
+              observer = setupLayerObserver(element, handleHeightChange);
+            });
+          } else {
+            // No target layer found, just show the component
+            isFirstRender = false;
+          }
+        } else {
+          // No grid content, just show the component
+          isFirstRender = false;
+        }
+      });
+    } else {
+      // No heightFrom, no need for measurement
+      isFirstRender = false;
+    }
+  });
+
+  // Effect to re-setup observer when either the target layer or heightFrom changes
+  $effect(() => {
+    // Only handle changes after initial setup
+    if (!isFirstRender && heightFrom && gridContent && !observer) {
+      initializeHeightTracking();
+    }
+  });
+
+  // Clean up on destroy
+  onDestroy(() => {
+    if (observer) {
+      observer.disconnect();
+      observer = null;
+    }
+  });
+
+</script>
+
+<div
+  data-component="grid-layers"
+  class="relative {isFirstRender ? 'invisible' : ''} {base} {bg} {heightFrom ? '' : height} {classes} {margin} {padding}"
+  style={containerStyle}
+  {...attrs}
+>
+  <div
+    data-section="grid"
+    bind:this={gridContent}
+    class="absolute inset-0 grid {cellBase} {cellBg} {cellPadding} {cellMargin} {cellClasses}"
+    style={cellStyle}
+    {...cellAttrs}
+  >
+    {@render children()}
+  </div>
+</div>
+
+<style>
+  /* All children of the layer share the same grid area
+     but aren't absolutely positioned */
+  [data-section='grid'] {
+    grid-template-columns: 1fr;
+    grid-template-rows: 1fr;
+  }
+
+  [data-section='grid'] > :global(*) {
+    grid-column: 1;
+    grid-row: 1;
+    z-index: 0; /* Base z-index to allow explicit stacking order */
+  }
+</style>

package/dist/ui/primitives/layout/grid-layers/util.js

@@ -1,74 +1,74 @@
-// lib/primitives/layout/gridLayers.utils.js
-
-/**
- * Sets up a ResizeObserver on the target layer
- * 
- * @param {HTMLElement|null} targetLayer - The layer element to observe
- * @param {Function} onHeightChange - Callback when height changes
- * @returns {ResizeObserver|null} - The created observer or null
- */
-export function setupLayerObserver(targetLayer, onHeightChange) {
-  if (!targetLayer || !window.ResizeObserver) return null;
-
-  // Create new observer
-  const observer = new ResizeObserver(entries => {
-    for (const entry of entries) {
-      if (entry.target === targetLayer) {
-        // Get the computed style to access margin values
-        const computedStyle = window.getComputedStyle(targetLayer);
-        const marginTop = parseInt(computedStyle.marginTop, 10);
-        const marginBottom = parseInt(computedStyle.marginBottom, 10);
-
-        // Calculate height including border box and margins
-        let elementHeight = 0;
-
-        if (entry.borderBoxSize) {
-          const borderBoxSize = Array.isArray(entry.borderBoxSize)
-            ? entry.borderBoxSize[0]
-            : entry.borderBoxSize;
-          elementHeight = borderBoxSize.blockSize;
-        } else {
-          // Fallback to getBoundingClientRect
-          const rect = targetLayer.getBoundingClientRect();
-          elementHeight = rect.height;
-        }
-
-        // Add margins to the height
-        const totalHeight = elementHeight + marginTop + marginBottom;
-        onHeightChange(totalHeight);
-      }
-    }
-  });
-
-  // Start observing
-  observer.observe(targetLayer);
-  return observer;
-}
-
-/**
- * Measures the height of the specified layer, including margins
- * 
- * @param {HTMLElement|null} container - The container to search in
- * @param {string} layerId - The data-layer attribute value to find
- * @returns {{ element: HTMLElement|null, height: number }} The element and its height
- */
-export function measureTargetLayer(container, layerId) {
-  if (!layerId || !container) return { element: null, height: 0 };
-
-  const layerElement = container.querySelector(`[data-layer="${layerId}"]`);
-  
-  if (!layerElement) return { element: null, height: 0 };
-  
-  // Get the computed style to access margin values
-  const computedStyle = window.getComputedStyle(layerElement);
-  const marginTop = parseInt(computedStyle.marginTop, 10);
-  const marginBottom = parseInt(computedStyle.marginBottom, 10);
-  
-  // Get the element's border box height
-  const rect = layerElement.getBoundingClientRect();
-  
-  // Calculate total height including margins
-  const height = rect.height > 0 ? rect.height + marginTop + marginBottom : 0;
-  
-  return { element: layerElement, height };
-}
+// lib/primitives/layout/gridLayers.utils.js
+
+/**
+ * Sets up a ResizeObserver on the target layer
+ * 
+ * @param {HTMLElement|null} targetLayer - The layer element to observe
+ * @param {Function} onHeightChange - Callback when height changes
+ * @returns {ResizeObserver|null} - The created observer or null
+ */
+export function setupLayerObserver(targetLayer, onHeightChange) {
+  if (!targetLayer || !window.ResizeObserver) return null;
+
+  // Create new observer
+  const observer = new ResizeObserver(entries => {
+    for (const entry of entries) {
+      if (entry.target === targetLayer) {
+        // Get the computed style to access margin values
+        const computedStyle = window.getComputedStyle(targetLayer);
+        const marginTop = parseInt(computedStyle.marginTop, 10);
+        const marginBottom = parseInt(computedStyle.marginBottom, 10);
+
+        // Calculate height including border box and margins
+        let elementHeight = 0;
+
+        if (entry.borderBoxSize) {
+          const borderBoxSize = Array.isArray(entry.borderBoxSize)
+            ? entry.borderBoxSize[0]
+            : entry.borderBoxSize;
+          elementHeight = borderBoxSize.blockSize;
+        } else {
+          // Fallback to getBoundingClientRect
+          const rect = targetLayer.getBoundingClientRect();
+          elementHeight = rect.height;
+        }
+
+        // Add margins to the height
+        const totalHeight = elementHeight + marginTop + marginBottom;
+        onHeightChange(totalHeight);
+      }
+    }
+  });
+
+  // Start observing
+  observer.observe(targetLayer);
+  return observer;
+}
+
+/**
+ * Measures the height of the specified layer, including margins
+ * 
+ * @param {HTMLElement|null} container - The container to search in
+ * @param {string} layerId - The data-layer attribute value to find
+ * @returns {{ element: HTMLElement|null, height: number }} The element and its height
+ */
+export function measureTargetLayer(container, layerId) {
+  if (!layerId || !container) return { element: null, height: 0 };
+
+  const layerElement = container.querySelector(`[data-layer="${layerId}"]`);
+  
+  if (!layerElement) return { element: null, height: 0 };
+  
+  // Get the computed style to access margin values
+  const computedStyle = window.getComputedStyle(layerElement);
+  const marginTop = parseInt(computedStyle.marginTop, 10);
+  const marginBottom = parseInt(computedStyle.marginBottom, 10);
+  
+  // Get the element's border box height
+  const rect = layerElement.getBoundingClientRect();
+  
+  // Calculate total height including margins
+  const height = rect.height > 0 ? rect.height + marginTop + marginBottom : 0;
+  
+  return { element: layerElement, height };
+}

package/dist/ui/primitives/layout/index.js

@@ -1 +1 @@
-export { default as GridLayers } from './grid-layers/GridLayers.svelte';
+export { default as GridLayers } from './grid-layers/GridLayers.svelte';

package/dist/ui/primitives/panels/index.js

@@ -1 +1 @@
-export { default as Panel } from './panel/Panel.svelte';
+export { default as Panel } from './panel/Panel.svelte';