@hkdigital/lib-sveltekit 0.2.7 → 0.2.8

package/dist/components/layout/grid-layers/GridLayers.svelte__heightFrom__

@@ -1,372 +0,0 @@
-<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>