/**
 * layout-extra.css
 *
 * A supplementary library of layout-focused mixins, functions, and utilities.
 * ------------------------------------------------------------------------------
 * This file extends the core layout system by providing two things:
 *
 * 1.  PROPOSED MIXINS/FUNCTIONS: For applying layout patterns directly in CSS to
 *     any element, offering a CSS-centric approach.
 *
 * 2.  UTILITY CLASSES: For augmenting the behavior of the <layout-*> components
 *     with common visual effects and behaviors (e.g., shadows, sticky positioning).
 *
 * ==============================================================================
 * ⚠️ IMPORTANT: PROPOSED FEATURE NOTICE ⚠️
 * The @function and @mixin rules are NOT SUPPORTED in any browser as of late 2025.
 * This file demonstrates a forward-looking, pre-processor-free approach.
 * ==============================================================================
 *
 * --- TABLE OF CONTENTS ---
 *
 * 1.  LAYOUT MIXINS
 *     - `@mixin --layout-stack`
 *     - `@mixin --layout-grid`
 *     - `@mixin --layout-sidebar`
 *
 * 2.  LAYOUT FUNCTIONS
 *     - `@function --aspect-ratio`
 *
 * 3.  UTILITY CLASSES
 *     - `.has-shadow-sm`, `.has-shadow-md`, `.has-shadow-lg`
 *     - `.is-sticky`
 *     - `.is-full-bleed`
 *
 */

/*
 * ==============================================================================
 * 1. LAYOUT MIXINS (Proposed Syntax)
 * ==============================================================================
 * These mixins allow you to apply the logic of the layout components to any
 * standard HTML element in your own stylesheets.
 */

/**
 * @mixin --layout-stack
 * Applies vertical stacking logic to the current selector.
 *
 * @param {<length>} --gap - The space between stacked items.
 * @param {string} --align - The horizontal alignment of items.
 *
 * @example
 *   .product-details {
 *     @apply --layout-stack(--gap: 2rem, --align: flex-start);
 *   }
 */
@mixin --layout-stack(--gap, --align: stretch) {
  display: flex;
  flex-direction: column;
  justify-content: flex-start;
  align-items: var(--align);
  gap: var(--gap, var(--space-md, 1.5rem));
}

/**
 * @mixin --layout-grid
 * Applies responsive grid logic to the current selector.
 *
 * @param {string} --min-item-size - The minimum size for each grid item.
 * @param {<length>} --gap - The gap between items.
 *
 * @example
 *   .card-collection {
 *     @apply --layout-grid(--min-item-size: 20rem);
 *   }
 */
@mixin --layout-grid(--min-item-size, --gap) {
  display: grid;
  gap: var(--gap, var(--space-md, 1.5rem));
  grid-template-columns: repeat(auto-fit, minmax(min(100%, var(--min-item-size, 16rem)), 1fr));
}

/**
 * @mixin --layout-sidebar
 * Applies the logic for a responsive sidebar layout.
 *
 * @param {string} --side-width - The width of the sidebar.
 * @param {string} --content-min - The point at which the main content wraps.
 * @param {<length>} --gap - The space between sidebar and content.
 *
 * @example
 *   main.with-sidebar {
 *     @apply --layout-sidebar(--side-width: 250px);
 *
 *     & > :last-child {
 *       flex-basis: var(--side-width); // Match sidebar width
 *     }
 *   }
 */
@mixin --layout-sidebar(--side-width, --content-min, --gap) {
  display: flex;
  flex-wrap: wrap;
  gap: var(--gap, var(--space-lg, 2rem));

  & > :first-child { /* Main content */
    flex-grow: 9999;
    flex-basis: var(--content-min, 50%);
  }
  & > :last-child { /* Sidebar */
    flex-grow: 1;
    flex-basis: var(--side-width, 20rem);
  }
}


/*
 * ==============================================================================
 * 2. LAYOUT FUNCTIONS (Proposed Syntax)
 * ==============================================================================
 */

/**
 * @function --aspect-ratio
 * A simple function to return a clean aspect-ratio value.
 *
 * @param {<number>} --width - The width component of the ratio.
 * @param {<number>} --height - The height component of the ratio.
 * @returns {string} The aspect-ratio value (e.g., "16 / 9").
 *
 * @example
 *   .video-player {
 *     aspect-ratio: --aspect-ratio(16, 9);
 *   }
 */
@function --aspect-ratio(--width type(*), --height type(*)) returns type(*) {
  result: var(--width) + ' / ' + var(--height);
}


/*
 * ==============================================================================
 * 3. UTILITY CLASSES
 * ==============================================================================
 * These classes can be added to layout components (or any element) to apply
 * common, shared visual effects and behaviors.
 */

/**
 * Shadow Utilities
 * Apply consistent, token-based shadows.
 *
 * @example
 *   <layout-sidebar class="has-shadow-md">...</layout-sidebar>
 */
:where(.has-shadow-sm, .has-shadow-md, .has-shadow-lg) {
  /* Assumes shadow tokens are defined in a global file like `base.css` */
  --_shadow-sm: var(--shadow-1, 0 1px 3px rgb(0 0 0 / 0.1));
  --_shadow-md: var(--shadow-2, 0 4px 6px rgb(0 0 0 / 0.1));
  --_shadow-lg: var(--shadow-3, 0 10px 15px rgb(0 0 0 / 0.1));
}
.has-shadow-sm { box-shadow: var(--_shadow-sm); }
.has-shadow-md { box-shadow: var(--_shadow-md); }
.has-shadow-lg { box-shadow: var(--_shadow-lg); }


/**
 * Sticky Positioning Utility
 * Makes an element "stick" to the top of its scrolling container.
 * Perfect for sidebars or headers.
 *
 * @example
 *   <layout-sidebar>
 *     <main>...</main>
 *     <aside class="is-sticky">...</aside>
 *   </layout-sidebar>
 */
.is-sticky {
  --_sticky-top: var(--sticky-top-offset, 1rem); /* Customizable offset */

  position: sticky;
  top: var(--_sticky-top);
  align-self: start; /* Prevents stretching in flex/grid containers */
  max-height: calc(100vh - var(--_sticky-top) * 2); /* Prevents overflow */
  overflow-y: auto;
}


/**
 * Full Bleed Utility
 * Allows a child element to break out of its parent container's padding
 * and stretch to the full width of the viewport.
 *
 * @example
 *   <layout-center>
 *     <p>This text is constrained.</p>
 *     <img src="..." alt="..." class="is-full-bleed">
 *     <p>This text is also constrained.</p>
 *   </layout-center>
 */
.is-full-bleed {
  width: 100vw;
  margin-inline: 50%;
  transform: translateX(-50%);
}