/* ==========================================================================
   DS v3 — Noise Grain Utility (utilities/noise.css)
   Issue: #224 · Parent: #192 (FASE-4 Polish)
   ==========================================================================

   Sistema de textura de ruído do DS v3 Spatial Glass.

   FUNDAMENTO:
   Vidro real tem micro-imperfeições que quebram a uniformidade especular.
   O noise grain SVG simula essa textura via feTurbulence (fractalNoise),
   aplicado com mix-blend-mode: overlay para adicionar profundidade material
   sem alterar as cores dominantes da superfície.

   ARQUITETURA:
   O token `--ds-glass-noise-url` é definido uma única vez em tokens/glass.css.
   O parser CSS compartilha o valor entre todos os sites de uso — não há
   duplicação de dados em memória (1 objeto por página, independente de quantos
   elementos usam a variável).

   HIERARQUIA DE USO:
   1. `.ds-glass` (utilities/glass.css) — noise via `::after` automático
      Para toda superfície glass principal. NÃO adicionar .ds-noise nestes.
   2. `.ds-noise` (este arquivo) — para superfícies SEM .ds-glass
      Ex: backgrounds de página, containers de seção, cards non-glass.
   3. Componentes Shadow DOM (ds-header, ds-sidebar, ds-modal)
      LIMITAÇÃO: `::part()::after` não é válido em CSS.
      O noise nesses componentes deve ser aplicado internamente no shadow DOM
      via CSS adoptedStyleSheets do Web Component, usando var(--ds-glass-noise-url).
      Ver padrão de integração no fim deste arquivo.

   AUDITORIA FASE-4 (#224):
   ✅ --ds-glass-noise-url — SVG fractalNoise data URI (seed=42, grayscale)
   ✅ Reutilização global — 1 definição em tokens/glass.css, 0 inline
   ✅ Opacity 0.028 (light) / 0.045 (dark) — via tokens
   ✅ mix-blend-mode: overlay — aplicado em todos os sites de uso
   ✅ Zero requisições HTTP — data URI pura
   ✅ Nenhum componente declara fractalNoise inline (auditado em todos os .css e .ts)

   DEPENDÊNCIAS:
     tokens/glass.css — --ds-glass-noise-url, --ds-glass-noise-opacity-light/dark
   ========================================================================== */

@layer ds-utilities {

  /* ══════════════════════════════════════════════════════════════════════════
     .ds-noise — Noise grain standalone
     Para superfícies que NÃO usam .ds-glass.
     Uso: sections, hero areas, banners, backgrounds de módulo.
  ══════════════════════════════════════════════════════════════════════════ */

  .ds-noise {
    position: relative;
    /*
      Sem isolation: isolate aqui — o elemento pode não precisar de
      stacking context próprio. Se filhos usarem z-index, o consumidor
      deve adicionar isolation: isolate manualmente ou usar .ds-glass.
    */
  }

  /*
    ::after aplica o grain acima do conteúdo mas como overlay neutro.
    pointer-events: none garante que não intercepta cliques, toque ou
    seleção de texto no conteúdo abaixo.

    z-index: 0 dentro do stacking context local posiciona o grain acima
    do background mas abaixo dos filhos posicionados. Se o elemento não
    criar stacking context, z-index: 0 é inerte — sem efeito colateral.
  */
  .ds-noise::after {
    content: '';
    position: absolute;
    inset: 0;
    background-image: var(--ds-glass-noise-url);
    background-size: 200px 200px;
    opacity: var(--ds-glass-noise-opacity-light, 0.028);
    mix-blend-mode: overlay;
    pointer-events: none;
    border-radius: inherit;   /* herda border-radius do pai — noise não vaza para fora */
    z-index: 0;
  }

  /* Dark theme: opacidade maior para compensar menor contraste */
  [data-theme="dark"] .ds-noise::after,
  :root[data-theme-effective="dark"] .ds-noise::after {
    opacity: var(--ds-glass-noise-opacity-dark, 0.045);
  }

  /* ── Variante forte — superfícies com very high contrast (infográficos) ── */
  /*
    Double de opacidade: 0.056 (light) / 0.090 (dark).
    Uso restrito a heroes, splash screens, headers de seção grandes
    onde a textura é parte da identidade visual, não apenas detalhe.
    NÃO usar em cards, tabelas ou formulários — ruído distrai a leitura.
  */
  .ds-noise--strong::after {
    opacity: calc(var(--ds-glass-noise-opacity-light, 0.028) * 2);
  }

  [data-theme="dark"] .ds-noise--strong::after,
  :root[data-theme-effective="dark"] .ds-noise--strong::after {
    opacity: calc(var(--ds-glass-noise-opacity-dark, 0.045) * 2);
  }

  /* ── Acessibilidade: prefers-contrast: more ─────────────────────────── */
  /*
    Em alto contraste, textura visual pode criar ilusão de bordas ou
    divisões inexistentes — perturbador para usuários com baixa visão.
    Desativa completamente o grain.
  */
  @media (prefers-contrast: more) {
    .ds-noise::after,
    .ds-noise--strong::after {
      display: none;
    }
  }

  /* ── Performance: data-glass-reduced ────────────────────────────────── */
  /*
    Em dispositivos lentos (slow-2g, saveData), remover o noise reduz
    compositing layers. O noise é puramente decorativo — sem impacto funcional.
  */
  [data-glass-reduced] .ds-noise::after,
  [data-glass-reduced] .ds-noise--strong::after {
    display: none;
  }

}

/* ==========================================================================
   PADRÃO DE INTEGRAÇÃO — Componentes Shadow DOM
   ==========================================================================

   Componentes Web que usam Shadow DOM (ds-header, ds-sidebar, ds-modal)
   NÃO podem receber noise via `::part()::after` — a CSS Part API não permite
   pseudo-elementos em partes expostas de fora do shadow tree.

   SOLUÇÃO RECOMENDADA: adicionar internamente ao adoptedStyleSheet do WC:

     // Dentro do Web Component TypeScript (ex: ds-header.ts):
     static styles = css`
       :host::before {
         content: '';
         position: absolute;
         inset: 0;
         background-image: var(--ds-glass-noise-url);
         background-size: 200px 200px;
         /*
           NÃO adicionar override para dark mode aqui.
           tokens/glass.css já sobrescreve --ds-glass-noise-opacity-light
           com o valor dark (0.045) via [data-theme="dark"] e :root[data-theme-effective="dark"].
           Custom properties CSS HERDAM através da fronteira shadow DOM —
           o token com valor correto chega aqui automaticamente.

           ERRADO: :host([data-theme="dark"])::before { ... }
           O atributo data-theme fica em :root, nunca no elemento host.
         */
         opacity: var(--ds-glass-noise-opacity-light, 0.028);
         mix-blend-mode: overlay;
         pointer-events: none;
         z-index: 0;
       }
     `;

   ALTERNATIVA CSS PURA (sem pseudo-elemento):
   Stacked background-image no ::part() — noise como segunda camada.
   Limitação: background-blend-mode blenda com background-color (não com o
   conteúdo abaixo), comportamento diferente de mix-blend-mode: overlay.
   Resultado visual é aceitável apenas em surfaces escuras.

     ds-header::part(header) {
       background-image:
         var(--ds-glass-noise-url),
         linear-gradient(...);  // ou background existente como image
       background-blend-mode: overlay, normal;
       background-size: 200px 200px, auto;
     }

   ESTADO ATUAL (2026-02-23):
   - ds-header: sem noise interno (pending WC update)
   - ds-sidebar: sem noise interno (pending WC update)
   - ds-modal: sem noise interno (pending WC update)
   Impacto visual: mínimo — o noise é um detalhe de materialidade em
   profundidades 0.028–0.045 de opacidade. Não afeta legibilidade.
   ========================================================================== */