strata-css 1.0.0

package/src/components/modules/skeleton.js

@@ -0,0 +1,334 @@
+/**
+ * Strata Skeleton JS Utility
+ * Version: 1.0.0
+ *
+ * Smart detection and lifecycle management for skeleton loaders.
+ * JS handles detection and toggling only.
+ * CSS handles all visual rendering via @layer st-skeleton.
+ *
+ * Four attribute states:
+ *   "true"  — element shimmers (CSS applies ::before overlay)
+ *   "false" — element revealed (no shimmer)
+ *   "null"  — JS managed parent (no overlay, children shimmer individually)
+ *
+ * Key fix: replaced elements (img, video, iframe) cannot have ::before
+ * pseudo-elements in browsers. JS marks their WRAPPER div with "true"
+ * instead so the wrapper's ::before overlay covers the replaced content.
+ */
+
+;(function (global) {
+  'use strict'
+
+  // ─── Element type sets ───────────────────────────────────────────────
+
+  // Content elements that support ::before — become individual skeleton bars
+  const CONTENT_TAGS = new Set([
+    'P', 'H1', 'H2', 'H3', 'H4', 'H5', 'H6',
+    'SPAN', 'A', 'LABEL', 'STRONG', 'EM', 'SMALL',
+    'BUTTON', 'INPUT', 'TEXTAREA', 'SELECT',
+    'LI', 'DT', 'DD', 'BLOCKQUOTE', 'FIGCAPTION'
+    // NOTE: IMG, VIDEO, IFRAME are NOT here —
+    // replaced elements cannot have ::before.
+    // Their parent WRAPPER is marked instead.
+  ])
+
+  // Replaced elements — ::before not supported by browsers
+  // JS marks their wrapper parent instead
+  const REPLACED_TAGS = new Set([
+    'IMG', 'VIDEO', 'IFRAME', 'PICTURE', 'CANVAS', 'SVG'
+  ])
+
+  // Structural elements — skipped, children scanned
+  // UNLESS they contain only replaced elements, in which case
+  // the structural element itself becomes the skeleton bar
+  const STRUCTURAL_TAGS = new Set([
+    'DIV', 'SECTION', 'ARTICLE', 'MAIN', 'ASIDE',
+    'HEADER', 'FOOTER', 'NAV', 'UL', 'OL', 'DL',
+    'FIGURE', 'FORM', 'FIELDSET'
+  ])
+
+  // Tags to ignore completely
+  const IGNORE_TAGS = new Set([
+    'SCRIPT', 'STYLE', 'NOSCRIPT', 'META', 'LINK',
+    'HEAD', 'HTML', 'BODY', 'BR', 'HR', 'WBR'
+  ])
+
+  // ─── Registry ────────────────────────────────────────────────────────
+
+  const registry = new Map()
+
+  // ─── Smart Detection ─────────────────────────────────────────────────
+
+  /**
+   * Check if an element has direct text nodes (not just whitespace)
+   */
+  function hasDirectText(el) {
+    return Array.from(el.childNodes).some(
+      node => node.nodeType === Node.TEXT_NODE
+           && node.textContent.trim().length > 0
+    )
+  }
+
+  /**
+   * Check if a structural element contains ONLY replaced elements.
+   * If so, the structural element itself becomes the skeleton bar
+   * because its ::before overlay covers the replaced content.
+   *
+   * Example: <div class="card-img-wrap"><img src="..."></div>
+   * → card-img-wrap gets "true", its ::before covers the img
+   */
+  function hasOnlyReplacedChildren(el) {
+    const meaningful = Array.from(el.children).filter(
+      c => !IGNORE_TAGS.has(c.tagName)
+    )
+    return meaningful.length > 0
+        && meaningful.every(c => REPLACED_TAGS.has(c.tagName))
+  }
+
+  /**
+   * Walk the DOM from a parent and find all leaf nodes.
+   *
+   * Rules:
+   * - Content tags (p, h3, button, a etc.) → mark as skeleton bar
+   * - Structural wrapper containing ONLY replaced elements (img, video) →
+   *   mark the WRAPPER as skeleton bar (its ::before covers the media)
+   * - Structural wrapper with direct text → mark as skeleton bar
+   * - Structural wrapper with mixed children → recurse
+   * - Replaced elements (img, video) as direct children → skip
+   *   (handled by their parent wrapper rule above)
+   * - data-st-skeleton="false" → skip element and all descendants
+   * - data-st-skeleton="null" → skip (another managed parent)
+   */
+  function detectLeaves(parent) {
+    const leaves = []
+
+    function walk(el) {
+      // Skip opted-out elements entirely
+      if (el.getAttribute('data-st-skeleton') === 'false') return
+
+      // Skip other managed JS parents
+      if (el !== parent && el.getAttribute('data-st-skeleton') === 'null') return
+
+      // Skip ignored tags
+      if (IGNORE_TAGS.has(el.tagName)) return
+
+      const tag = el.tagName
+
+      // Content element — supports ::before, mark as leaf
+      if (CONTENT_TAGS.has(tag)) {
+        leaves.push(el)
+        return
+      }
+
+      // Replaced element as direct child of managed parent
+      // Cannot mark it — no ::before support. Skip it.
+      // Ideally developer wraps their images in a div.
+      if (REPLACED_TAGS.has(tag)) {
+        return
+      }
+
+      // Structural element — decide whether to mark or recurse
+      if (STRUCTURAL_TAGS.has(tag)) {
+
+        // CASE 1: Contains only replaced elements (img, video etc.)
+        // Mark THIS structural element — its ::before covers the media
+        if (hasOnlyReplacedChildren(el)) {
+          leaves.push(el)
+          return
+        }
+
+        // CASE 2: Has direct text — mark as leaf
+        if (hasDirectText(el)) {
+          leaves.push(el)
+          return
+        }
+
+        // CASE 3: Mixed children — recurse into children
+        Array.from(el.children).forEach(child => walk(child))
+        return
+      }
+
+      // Unknown tag — recurse into children
+      Array.from(el.children).forEach(child => walk(child))
+    }
+
+    // Walk children — not the parent itself
+    Array.from(parent.children).forEach(child => walk(child))
+
+    return leaves
+  }
+
+  // ─── Core ─────────────────────────────────────────────────────────────
+
+  /**
+   * Register a parent for JS management.
+   * Sets parent to "null" — neutral container, no parent overlay.
+   * Runs smart detection and marks leaf children with "true".
+   */
+  function manage(parent, options = {}) {
+    if (!parent || registry.has(parent)) return
+
+    const leaves = detectLeaves(parent)
+    registry.set(parent, { leaves, options })
+
+    // Set parent to "null" — removes parent ::before overlay
+    // so only individual leaf shimmers show
+    parent.setAttribute('data-st-skeleton', 'null')
+
+    // Mark detected leaves as skeleton
+    leaves.forEach(leaf => leaf.setAttribute('data-st-skeleton', 'true'))
+  }
+
+  /**
+   * Show skeleton — parent to "null", leaves to "true"
+   */
+  function show(selector) {
+    const targets = resolveTargets(selector)
+    targets.forEach(parent => {
+      const entry = registry.get(parent)
+      if (!entry) return
+      parent.setAttribute('data-st-skeleton', 'null')
+      entry.leaves.forEach(leaf => leaf.setAttribute('data-st-skeleton', 'true'))
+    })
+  }
+
+  /**
+   * Reveal content — parent to "false", leaves to "false"
+   * Attribute stays in DOM — only value changes.
+   */
+  function reveal(selector, options = {}) {
+    if (typeof selector === 'object' && !isSelector(selector)) {
+      options  = selector
+      selector = null
+    }
+
+    const targets  = resolveTargets(selector)
+    const stagger  = options.stagger  || 0
+    const onReveal = options.onReveal || null
+
+    targets.forEach((parent, index) => {
+      const entry = registry.get(parent)
+      if (!entry) return
+
+      setTimeout(() => {
+        parent.setAttribute('data-st-skeleton', 'false')
+        entry.leaves.forEach(leaf => leaf.setAttribute('data-st-skeleton', 'false'))
+
+        if (onReveal && index === targets.length - 1) {
+          setTimeout(onReveal, 0)
+        }
+      }, stagger * index)
+    })
+  }
+
+  /**
+   * Toggle between skeleton and revealed
+   */
+  function toggle(selector) {
+    const targets = resolveTargets(selector)
+    targets.forEach(parent => {
+      const val = parent.getAttribute('data-st-skeleton')
+      val === 'false' ? show(parent) : reveal(parent)
+    })
+  }
+
+  /**
+   * Reveal one element by index within a selector group
+   */
+  function revealAt(selector, index) {
+    const targets = resolveTargets(selector)
+    const parent  = targets[index]
+    if (parent) reveal(parent)
+  }
+
+  /**
+   * Check if element is currently in skeleton state
+   */
+  function isSkeleton(el) {
+    const val = el.getAttribute('data-st-skeleton')
+    return val === 'true' || val === 'null'
+  }
+
+  // ─── Init ─────────────────────────────────────────────────────────────
+
+  /**
+   * Initialise the skeleton utility.
+   *
+   * No selector: auto-discovers all [data-st-skeleton="true"] top-level parents.
+   * With selector: manages all matching elements.
+   */
+  function init(selector, options = {}) {
+    let parents
+
+    if (!selector) {
+      // Auto-discover top-level skeleton parents
+      // Filter out elements that are children of another skeleton parent
+      parents = Array.from(
+        document.querySelectorAll('[data-st-skeleton="true"]')
+      ).filter(el => !el.parentElement.closest('[data-st-skeleton]'))
+
+    } else {
+      parents = resolveRaw(selector)
+
+      // Set initial attribute if missing
+      parents.forEach(parent => {
+        if (!parent.hasAttribute('data-st-skeleton')) {
+          parent.setAttribute('data-st-skeleton', 'true')
+        }
+      })
+    }
+
+    parents.forEach(parent => manage(parent, options))
+    return api
+  }
+
+  // ─── Helpers ──────────────────────────────────────────────────────────
+
+  function resolveTargets(selector) {
+    if (!selector) return Array.from(registry.keys())
+    if (selector instanceof Element) return registry.has(selector) ? [selector] : []
+    if (selector instanceof NodeList || Array.isArray(selector)) {
+      return Array.from(selector).filter(el => registry.has(el))
+    }
+    if (typeof selector === 'string') {
+      return Array.from(document.querySelectorAll(selector))
+        .filter(el => registry.has(el))
+    }
+    return []
+  }
+
+  function resolveRaw(selector) {
+    if (!selector) return []
+    if (selector instanceof Element) return [selector]
+    if (selector instanceof NodeList || Array.isArray(selector)) return Array.from(selector)
+    if (typeof selector === 'string') return Array.from(document.querySelectorAll(selector))
+    return []
+  }
+
+  function isSelector(val) {
+    return typeof val === 'string'
+      || val instanceof Element
+      || val instanceof NodeList
+  }
+
+  // ─── Public API ───────────────────────────────────────────────────────
+
+  const api = {
+    init,
+    show,
+    reveal,
+    toggle,
+    revealAt,
+    isSkeleton,
+    manage: (selector, options) => {
+      resolveRaw(selector).forEach(el => manage(el, options))
+      return api
+    }
+  }
+
+  // ─── Export ───────────────────────────────────────────────────────────
+
+  if (!global.Strata) global.Strata = {}
+  global.Strata.skeleton = api
+
+})(window)

package/src/components/strata.manifest.js

@@ -0,0 +1,15 @@
+/*!
+ * Strata Components — Entry Point
+ *
+ * This file is the bundle manifest.
+ * The build script concatenates all files in src/js/components/ (in filename order)
+ * and writes the result to dist/strata.components.js.
+ *
+ * To add a new component:
+ *   1. Create src/js/components/[name].js
+ *   2. Run: npm run build
+ *
+ * Current components:
+ *   modal.js    — Modal    (data-st-toggle, data-st-dismiss, data-st-backdrop)
+ *   skeleton.js — Skeleton (Strata.skeleton.init / show / reveal / toggle)
+ */

package/src/generator/generator.js

@@ -0,0 +1,113 @@
+/**
+ * Strata Generator — v4 — Sub-layer routing
+ *
+ * Each CSS rule is routed to its correct breakpoint sub-layer.
+ * Layer declaration order in base.js ensures correct cascade priority:
+ *
+ *   st-components-xs  < st-components-sm  < st-components-md  < ...
+ *   st-utilities-xs   < st-utilities-sm   < st-utilities-md   < ...
+ *
+ * This means HTML class order NEVER affects CSS behaviour.
+ * col-lg-4 always beats col-sm-8 at large screens regardless of
+ * which class appears first in the HTML attribute.
+ *
+ * Routing logic:
+ *   No media query      → xs sub-layer  (mobile first default)
+ *   min-width: 576px    → sm sub-layer
+ *   min-width: 768px    → md sub-layer
+ *   min-width: 992px    → lg sub-layer
+ *   min-width: 1200px   → xl sub-layer
+ *   min-width: 1400px   → xxl sub-layer
+ *
+ * Media query is kept inside the layer — it still controls when
+ * the style activates. The layer controls cascade priority between
+ * breakpoints.
+ */
+
+'use strict'
+
+const { lookup } = require('../registry/registry')
+
+// ─── Breakpoint routing ───────────────────────────────────────────────
+
+const BP_SUFFIX_MAP = [
+  { px: 1400, suffix: 'xxl' },
+  { px: 1200, suffix: 'xl'  },
+  { px:  992, suffix: 'lg'  },
+  { px:  768, suffix: 'md'  },
+  { px:  576, suffix: 'sm'  },
+]
+
+/**
+ * Determine which sub-layer suffix a CSS rule belongs to.
+ * Reads the min-width value from the @media query if present.
+ * Returns 'xs' for rules with no media query.
+ */
+function getSubLayerSuffix(css) {
+  const match = css.match(/@media\s*\(min-width:\s*(\d+(?:\.\d+)?)px\)/)
+  if (!match) return 'xs'
+  const px = parseFloat(match[1])
+  for (const { px: threshold, suffix } of BP_SUFFIX_MAP) {
+    if (px >= threshold) return suffix
+  }
+  return 'sm'
+}
+
+// ─── Generator ───────────────────────────────────────────────────────
+
+function generate(classNames, config = {}) {
+  // Buckets: layer → suffix → [css strings]
+  const buckets = {
+    components: { xs:[], sm:[], md:[], lg:[], xl:[], xxl:[] },
+    utilities:  { xs:[], sm:[], md:[], lg:[], xl:[], xxl:[] },
+  }
+
+  for (const cls of classNames) {
+    const result = lookup(cls)
+    if (!result) continue
+
+    const suffix = getSubLayerSuffix(result.css)
+    const group  = result.layer === 'components' ? 'components' : 'utilities'
+    buckets[group][suffix].push(result.css)
+  }
+
+  const SUFFIXES = ['xs', 'sm', 'md', 'lg', 'xl', 'xxl']
+
+  const componentParts = []
+  const utilityParts   = []
+
+  for (const suffix of SUFFIXES) {
+    if (buckets.components[suffix].length > 0) {
+      const layerName = `st-components-${suffix}`
+      const body = buckets.components[suffix].map(r => indent(r)).join('\n\n')
+      componentParts.push(`@layer ${layerName} {\n${body}\n}`)
+    }
+    if (buckets.utilities[suffix].length > 0) {
+      const layerName = `st-utilities-${suffix}`
+      const body = buckets.utilities[suffix].map(r => indent(r)).join('\n\n')
+      utilityParts.push(`@layer ${layerName} {\n${body}\n}`)
+    }
+  }
+
+  const componentCSS = componentParts.join('\n\n')
+  const utilityCSS   = utilityParts.join('\n\n')
+
+  return { componentCSS, utilityCSS }
+}
+
+function indent(css) {
+  return css.split('\n').map(line => '  ' + line).join('\n')
+}
+
+// Keep generateAST for compatibility
+function generateAST(classNames, config = {}) {
+  const postcss = require('postcss')
+  const { componentCSS, utilityCSS } = generate(classNames, config)
+
+  return {
+    componentAST: componentCSS ? postcss.parse(componentCSS) : null,
+    utilityAST:   utilityCSS   ? postcss.parse(utilityCSS)   : null,
+  }
+}
+
+module.exports = { generate, generateAST }

package/src/index.js

@@ -0,0 +1,172 @@
+/**
+ * Strata CSS — PostCSS Plugin — Optimised v6
+ *
+ * Warm builds bypass PostCSS entirely — no node creation, no GC pressure
+ * Cold builds run full PostCSS pipeline (including autoprefixer etc.)
+ * Warm builds return cached string directly — zero object allocation
+ */
+
+'use strict'
+
+const path = require('path')
+const fs   = require('fs')
+let postcss
+
+// ─── State ────────────────────────────────────────────────────────────
+let dirty      = true
+let cachedCSS  = null   // final output CSS string from last cold build
+
+// ─── Config cache ─────────────────────────────────────────────────────
+let cachedConfig      = null
+let cachedConfigPath  = null
+let cachedConfigMtime = 0
+
+function loadConfig(cwd) {
+  const configPath = path.resolve(cwd, 'strata.config.js')
+  let mtime = 0
+  try { mtime = fs.statSync(configPath).mtimeMs } catch {}
+  if (cachedConfig && cachedConfigPath === configPath && cachedConfigMtime === mtime) {
+    return cachedConfig
+  }
+  try {
+    delete require.cache[require.resolve(configPath)]
+    cachedConfig      = require(configPath)
+    cachedConfigPath  = configPath
+    cachedConfigMtime = mtime
+  } catch { cachedConfig = {} }
+  return cachedConfig
+}
+
+// ─── Base CSS ─────────────────────────────────────────────────────────
+const BASE_CSS = require('./layers/base').trim()
+let   BASE_AST = null
+
+function getBaseAST() {
+  if (!postcss) postcss = require('postcss')
+  if (!BASE_AST) BASE_AST = postcss.parse(BASE_CSS)
+  return BASE_AST
+}
+
+// ─── Input CSS cache ───────────────────────────────────────────────────
+// strata.css rarely changes — cache it with mtime check
+let cachedInputCSS   = null
+let cachedInputPath  = null
+let cachedInputMtime = 0
+
+function readInputCSS(inputCSSPath) {
+  let mtime = 0
+  try { mtime = fs.statSync(inputCSSPath).mtimeMs } catch {}
+  if (cachedInputCSS && cachedInputPath === inputCSSPath && cachedInputMtime === mtime) {
+    return cachedInputCSS
+  }
+  cachedInputCSS   = fs.readFileSync(inputCSSPath, 'utf8')
+  cachedInputPath  = inputCSSPath
+  cachedInputMtime = mtime
+  return cachedInputCSS
+}
+
+// ─── PostCSS Plugin ───────────────────────────────────────────────────
+// Only runs on cold builds — warm builds bypass via strata.build()
+
+const plugin = (opts = {}) => ({
+  postcssPlugin: 'strata-css',
+
+  async Once(root) {
+    if (!postcss) postcss = require('postcss')
+
+    const cwd    = opts.cwd || process.cwd()
+    const config = loadConfig(cwd)
+
+    const { scanFiles } = require('./scanner/scanner')
+    const { generate }  = require('./generator/generator')
+
+    const contentGlobs = config.content || [
+      './src/**/*.{html,jsx,tsx,vue,astro,svelte,js,ts}'
+    ]
+
+    const classNames = scanFiles(contentGlobs)
+    const { componentCSS, utilityCSS } = generate(classNames, config)
+
+    // Replace @strata directives
+    let baseInserted = false
+    root.walkAtRules('strata', rule => {
+      const d = rule.params.trim()
+      if (d === 'base' && !baseInserted) {
+        rule.replaceWith(getBaseAST().clone())
+        baseInserted = true
+      } else if (d === 'components') {
+        // componentCSS now contains multiple @layer sub-layer blocks
+        componentCSS ? rule.replaceWith(postcss.parse(componentCSS)) : rule.remove()
+      } else if (d === 'utilities') {
+        // utilityCSS now contains multiple @layer sub-layer blocks
+        utilityCSS ? rule.replaceWith(postcss.parse(utilityCSS)) : rule.remove()
+      } else {
+        rule.remove()
+      }
+    })
+  }
+})
+
+plugin.postcss = true
+module.exports = plugin
+
+// ─── Build API — used by CLI ──────────────────────────────────────────
+// Warm builds bypass PostCSS entirely — zero allocation, zero GC pressure
+
+module.exports.build = async (inputCSSPath, outputCSSPath, opts = {}) => {
+  // ── Warm path: return cached CSS, no work at all ──────────────────
+  if (!dirty && cachedCSS) {
+    if (outputCSSPath) fs.writeFileSync(outputCSSPath, cachedCSS)
+    return cachedCSS
+  }
+
+  // ── Cold path: string assembly — no PostCSS parse/stringify ───────
+  // PostCSS parse → AST clone → replaceWith → stringify is a costly
+  // round-trip that adds no transformation. We replace @strata directives
+  // via regex on the raw string, which is O(n) on the input file only.
+  const cwd    = opts.cwd || process.cwd()
+  const config = loadConfig(cwd)
+
+  const { scanFiles } = require('./scanner/scanner')
+  const { generate }  = require('./generator/generator')
+
+  const contentGlobs = config.content || [
+    './src/**/*.{html,jsx,tsx,vue,astro,svelte,js,ts}'
+  ]
+
+  const classNames = scanFiles(contentGlobs)
+  const { componentCSS, utilityCSS } = generate(classNames, config)
+
+  // Read input CSS (cached by mtime — strata.css rarely changes)
+  const inputCSS = readInputCSS(inputCSSPath)
+
+  // Replace @strata directives with pre-built CSS strings.
+  // Use function replacements (not string literals) so any `$` sequences
+  // in the CSS (e.g. inside comments) are never treated as regex back-references.
+  const css = inputCSS
+    .replace(/^\s*@strata\s+base\s*;/m,       () => BASE_CSS)
+    .replace(/^\s*@strata\s+components\s*;/m, () => componentCSS || '')
+    .replace(/^\s*@strata\s+utilities\s*;/m,  () => utilityCSS   || '')
+
+  cachedCSS = css
+  dirty     = false
+
+  if (outputCSSPath) {
+    fs.mkdirSync(path.dirname(outputCSSPath), { recursive: true })
+    fs.writeFileSync(outputCSSPath, css)
+  }
+
+  return css
+}
+
+// ─── Cache invalidation ───────────────────────────────────────────────
+module.exports.invalidate = (changedFile) => {
+  dirty     = true
+  cachedCSS = null
+  const { clearFileCache } = require('./scanner/scanner')
+  clearFileCache(changedFile)
+}
+
+// ─── Direct PostCSS usage (for users using postcss.config.js) ────────
+// Warm path still applies — cached CSS is injected as a raw parse
+module.exports.postcss = true