@epoch32/visage 0.0.0-stage → 1.0.0

package/src/style/parser.ts

@@ -0,0 +1,257 @@
+export interface ScopeOptions {
+  scopeId: string;
+  passToChildren?: boolean;
+}
+
+/**
+ * Scope a single CSS selector string with the given scope identifier
+ */
+export function scopeSelector(selector: string, options: ScopeOptions): string {
+  const { scopeId, passToChildren = false } = options;
+  const scopeAttr = `[data-${scopeId}]`;
+
+  // Split by comma for multiple selectors (e.g. "h1, h2, .title")
+  const parts = splitSelectorList(selector);
+
+  return parts
+    .map((part) => {
+      const trimmed = part.trim();
+      if (!trimmed) return "";
+
+      // 1. Check for :global() wrapper
+      if (trimmed.includes(":global(") || trimmed.includes("::v-global(")) {
+        return trimmed
+          .replace(
+            /(.*?)(?:::v-global|:global)\(([^)]+)\)(.*)/g,
+            (_match, before, globalTarget, after) => {
+              const prefix = before.trim();
+              const scopedPrefix = prefix ? scopeCompoundSelector(prefix, scopeAttr) : "";
+              if (scopedPrefix) {
+                return `${scopedPrefix} ${globalTarget.trim()}${after}`;
+              }
+              return `${globalTarget.trim()}${after}`;
+            }
+          )
+          .trim();
+      }
+
+      // 2. Check for :deep() / ::v-deep() wrapper
+      if (trimmed.includes(":deep(") || trimmed.includes("::v-deep(")) {
+        // e.g. ".parent :deep(.child)" -> ".parent[data-v-xyz] .child" or "[data-v-xyz] .child"
+        return trimmed
+          .replace(
+            /(.*?)(?:::v-deep|:deep)\(([^)]+)\)(.*)/g,
+            (_match, before, deepTarget, after) => {
+              const prefix = before.trim();
+              const scopedPrefix = prefix ? scopeCompoundSelector(prefix, scopeAttr) : scopeAttr;
+              return `${scopedPrefix} ${deepTarget.trim()}${after}`;
+            }
+          )
+          .trim();
+      }
+
+      // 3. Standard scoped selector
+      if (passToChildren) {
+        const compound = scopeCompoundSelector(trimmed, scopeAttr);
+        return `${scopeAttr} ${trimmed}, ${compound}`;
+      }
+
+      return scopeCompoundSelector(trimmed, scopeAttr);
+    })
+    .filter(Boolean)
+    .join(", ");
+}
+
+/**
+ * Scope a compound selector (e.g. ".card > .title.active:hover")
+ */
+function scopeCompoundSelector(selector: string, scopeAttr: string): string {
+  // Combinators: space, >, +, ~
+  const combinatorRegex = /([ >+~]+)/;
+  const tokens = selector.split(combinatorRegex);
+
+  const scopedTokens = tokens.map((token, index) => {
+    // If it's a combinator (odd index), leave as is
+    if (index % 2 === 1) return token;
+
+    const piece = token.trim();
+    if (!piece || piece === "*") return piece ? `${piece}${scopeAttr}` : "";
+
+    // If pseudo-element exists (e.g. ::before, ::after), insert before it
+    const pseudoElemIdx = piece.indexOf("::");
+    if (pseudoElemIdx !== -1) {
+      const base = piece.slice(0, pseudoElemIdx);
+      const pseudo = piece.slice(pseudoElemIdx);
+      return `${base}${scopeAttr}${pseudo}`;
+    }
+
+    // If pseudo-class exists (e.g. :hover, :focus, :nth-child(2)), insert before first pseudo-class
+    const pseudoClassIdx = piece.indexOf(":");
+    if (pseudoClassIdx !== -1) {
+      const base = piece.slice(0, pseudoClassIdx);
+      const pseudo = piece.slice(pseudoClassIdx);
+      return `${base}${scopeAttr}${pseudo}`;
+    }
+
+    return `${piece}${scopeAttr}`;
+  });
+
+  return scopedTokens.join("");
+}
+
+/**
+ * Split selector by commas while respecting parentheses (e.g. :is(.a, .b))
+ */
+function splitSelectorList(selectorList: string): string[] {
+  const result: string[] = [];
+  let depth = 0;
+  let current = "";
+
+  for (let i = 0; i < selectorList.length; i++) {
+    const char = selectorList[i];
+    if (char === "(") {
+      depth++;
+      current += char;
+    } else if (char === ")") {
+      depth = Math.max(0, depth - 1);
+      current += char;
+    } else if (char === "," && depth === 0) {
+      if (current.trim()) result.push(current.trim());
+      current = "";
+    } else {
+      current += char;
+    }
+  }
+
+  if (current.trim()) result.push(current.trim());
+  return result;
+}
+
+/**
+ * Full CSS block scoping transformer
+ */
+export function scopeCSS(css: string, options: ScopeOptions): string {
+  const { scopeId } = options;
+  const keyframeNames = new Set<string>();
+
+  // 1. Identify and extract @keyframes names
+  const keyframeRegex = /@(?:-webkit-)?keyframes\s+([a-zA-Z0-9_-]+)/g;
+  let kMatch: RegExpExecArray | null = keyframeRegex.exec(css);
+  while (kMatch !== null) {
+    if (kMatch[1]) {
+      keyframeNames.add(kMatch[1]);
+    }
+    kMatch = keyframeRegex.exec(css);
+  }
+
+  // 2. Tokenize and parse rules
+  let processed = css;
+
+  // Rename @keyframes definitions
+  for (const name of keyframeNames) {
+    const scopedName = `${scopeId}-${name}`;
+    const defRegex = new RegExp(`(@(?:-webkit-)?keyframes\\s+)${name}\\b`, "g");
+    processed = processed.replace(defRegex, `$1${scopedName}`);
+  }
+
+  // Replace animation property references to keyframes
+  if (keyframeNames.size > 0) {
+    for (const name of keyframeNames) {
+      const scopedName = `${scopeId}-${name}`;
+      const animRegex = new RegExp(`(animation(?:-name)?\\s*:[^;}]*?)\\b${name}\\b([^;}]*)`, "g");
+      processed = processed.replace(animRegex, `$1${scopedName}$2`);
+    }
+  }
+
+  // 3. Parse and rewrite CSS rules and nested blocks
+  return transformRules(processed, options);
+}
+
+function transformRules(css: string, options: ScopeOptions): string {
+  let output = "";
+  let i = 0;
+  const len = css.length;
+
+  while (i < len) {
+    // Skip whitespace
+    while (i < len && /\s/.test(css[i] as string)) {
+      output += css[i];
+      i++;
+    }
+    if (i >= len) break;
+
+    // Handle comments
+    if (css[i] === "/" && css[i + 1] === "*") {
+      const endComment = css.indexOf("*/", i + 2);
+      if (endComment === -1) {
+        output += css.slice(i);
+        break;
+      }
+      output += css.slice(i, endComment + 2);
+      i = endComment + 2;
+      continue;
+    }
+
+    // Find next block opener '{' or ';'
+    const openBrace = css.indexOf("{", i);
+    if (openBrace === -1) {
+      output += css.slice(i);
+      break;
+    }
+
+    const header = css.slice(i, openBrace).trim();
+
+    // Check if at-rule (like @media, @supports, @container, @keyframes)
+    if (header.startsWith("@")) {
+      if (
+        header.startsWith("@media") ||
+        header.startsWith("@supports") ||
+        header.startsWith("@container")
+      ) {
+        // Find matching closing brace for nested at-rule
+        const closeBrace = findMatchingBrace(css, openBrace);
+        const innerContent = css.slice(openBrace + 1, closeBrace);
+        const transformedInner = transformRules(innerContent, options);
+
+        output += `${header} {\n${transformedInner}\n}`;
+        i = closeBrace + 1;
+        continue;
+      }
+
+      if (header.includes("keyframes") || header.startsWith("@font-face")) {
+        // Keep keyframe and font-face blocks intact without selector scoping
+        const closeBrace = findMatchingBrace(css, openBrace);
+        output += css.slice(i, closeBrace + 1);
+        i = closeBrace + 1;
+        continue;
+      }
+    }
+
+    // Standard rule selector
+    const closeBrace = css.indexOf("}", openBrace);
+    if (closeBrace === -1) {
+      output += css.slice(i);
+      break;
+    }
+
+    const body = css.slice(openBrace + 1, closeBrace);
+    const scopedSelector = scopeSelector(header, options);
+
+    output += `${scopedSelector} {${body}}`;
+    i = closeBrace + 1;
+  }
+
+  return output;
+}
+
+function findMatchingBrace(str: string, openIndex: number): number {
+  let depth = 0;
+  for (let i = openIndex; i < str.length; i++) {
+    if (str[i] === "{") depth++;
+    else if (str[i] === "}") {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return str.length - 1;
+}

package/src/style/scale.ts

@@ -0,0 +1,237 @@
+/**
+ * Visage Spatial Engine & Style Primitives
+ *
+ * Eliminates measurement fatigue, layout bugs, and manual viewport calculations.
+ * Standardizes on a crisp 4px spatial scale, semantic viewport intents,
+ * fluid clamp calculations, and typed visual design tokens.
+ */
+
+export const UNITLESS_PROPERTIES = new Set([
+  "animationIterationCount",
+  "aspectRatio",
+  "borderImageSlice",
+  "columnCount",
+  "columns",
+  "flex",
+  "flexGrow",
+  "flexShrink",
+  "flexOrder",
+  "fontWeight",
+  "lineHeight",
+  "opacity",
+  "order",
+  "orphans",
+  "scale",
+  "tabSize",
+  "widows",
+  "zIndex",
+  "zoom",
+  "fillOpacity",
+  "strokeOpacity"
+]);
+
+export const DIMENSION_KEYWORDS: Record<string, string> = {
+  screen: "100dvh",
+  "screen-h": "100dvh",
+  "screen-w": "100dvw",
+  full: "100%",
+  half: "50%",
+  third: "33.333333%",
+  "two-thirds": "66.666667%",
+  quarter: "25%",
+  "three-quarters": "75%",
+  auto: "auto",
+  min: "min-content",
+  max: "max-content",
+  fit: "fit-content"
+};
+
+/**
+ * Resolves a spatial scale step or dimensional intent to a valid CSS measurement.
+ * Numbers map to the 4px engineering grid (1 = 4px, 2 = 8px, 4 = 16px, 8 = 32px).
+ *
+ * @example
+ * space(1)        // "4px"
+ * space(2)        // "8px"
+ * space(4)        // "16px"
+ * space(6)        // "24px"
+ * space("full")   // "100%"
+ * space("screen") // "100dvh"
+ */
+export function space(val: number | string | undefined | null): string {
+  if (val === undefined || val === null || val === "") return "";
+  if (typeof val === "number") {
+    if (val === 0) return "0px";
+    return `${val * 4}px`;
+  }
+  const str = String(val).trim();
+  if (str in DIMENSION_KEYWORDS) {
+    return DIMENSION_KEYWORDS[str]!;
+  }
+  return str;
+}
+
+/**
+ * Resolves width, height, or grid sizing into valid CSS.
+ * Small numbers (<= 48) map to the 4px scale, while larger numbers (> 48)
+ * are treated as explicit pixel dimensions.
+ */
+export function resolveDimension(val: number | string | undefined | null): string {
+  if (val === undefined || val === null || val === "") return "";
+  if (typeof val === "number") {
+    if (val === 0) return "0px";
+    if (val > 48) return `${val}px`;
+    return `${val * 4}px`;
+  }
+  const str = String(val).trim();
+  if (str in DIMENSION_KEYWORDS) {
+    return DIMENSION_KEYWORDS[str]!;
+  }
+  return str;
+}
+
+/**
+ * Explicit raw pixel measurement helper.
+ */
+export function px(val: number): string {
+  return `${val}px`;
+}
+
+/**
+ * Explicit rem measurement helper.
+ */
+export function rem(val: number): string {
+  return `${val}rem`;
+}
+
+/**
+ * Explicit em measurement helper.
+ */
+export function em(val: number): string {
+  return `${val}em`;
+}
+
+/**
+ * Computes an optimal fluid clamp() expression.
+ * Eliminates the math nightmare of manual linear viewport interpolation slopes.
+ *
+ * @param minPx Minimum size in pixels at mobile viewport
+ * @param maxPx Maximum size in pixels at desktop viewport
+ * @param options Min/max viewport bounds (defaults to 375px mobile and 1280px desktop)
+ *
+ * @example
+ * fluid(16, 32)
+ * // clamp(16px, 9.38px + 1.77vw, 32px)
+ */
+export function fluid(
+  minPx: number,
+  maxPx: number,
+  options?: { minVw?: number; maxVw?: number }
+): string {
+  const minVw = options?.minVw ?? 375;
+  const maxVw = options?.maxVw ?? 1280;
+  const slope = (maxPx - minPx) / (maxVw - minVw);
+  const yIntercept = -minVw * slope + minPx;
+  const slopeVw = slope * 100;
+  const preferred = `${yIntercept.toFixed(2)}px + ${slopeVw.toFixed(2)}vw`;
+  const min = Math.min(minPx, maxPx);
+  const max = Math.max(minPx, maxPx);
+  return `clamp(${min}px, ${preferred}, ${max}px)`;
+}
+
+export type ShadowVariant = "none" | "sm" | "md" | "lg" | "xl" | "soft" | "glow" | "inner";
+
+export const SHADOW_PRESETS: Record<ShadowVariant, string> = {
+  none: "none",
+  sm: "0 1px 2px 0 rgba(0, 0, 0, 0.05)",
+  md: "0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1)",
+  lg: "0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1)",
+  xl: "0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 8px 10px -6px rgba(0, 0, 0, 0.1)",
+  soft: "0 8px 30px rgba(0, 0, 0, 0.06)",
+  glow: "0 0 24px rgba(168, 85, 247, 0.35)",
+  inner: "inset 0 2px 4px 0 rgba(0, 0, 0, 0.06)"
+};
+
+/**
+ * Returns typed box-shadow tokens designed for high-contrast optical depth.
+ */
+export function shadow(variant: ShadowVariant | string): string {
+  if (variant in SHADOW_PRESETS) {
+    return SHADOW_PRESETS[variant as ShadowVariant]!;
+  }
+  return variant;
+}
+
+export type RadiusVariant = "none" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "full" | number;
+
+export const RADIUS_PRESETS: Record<string, string> = {
+  none: "0px",
+  sm: "4px",
+  md: "8px",
+  lg: "12px",
+  xl: "16px",
+  "2xl": "20px",
+  "3xl": "24px",
+  full: "9999px"
+};
+
+/**
+ * Returns typed border-radius tokens or scale numbers.
+ */
+export function radius(variant: RadiusVariant): string {
+  if (typeof variant === "number") {
+    return `${variant}px`;
+  }
+  if (variant in RADIUS_PRESETS) {
+    return RADIUS_PRESETS[variant]!;
+  }
+  return String(variant);
+}
+
+export interface GlassOptions {
+  blur?: number | string;
+  tint?: string;
+  border?: string;
+}
+
+/**
+ * Generates tactile glassmorphism CSS styles with backdrop filters and frosted borders.
+ */
+export function glass(options: GlassOptions = {}): Record<string, string> {
+  const blurVal = typeof options.blur === "number" ? `${options.blur}px` : (options.blur ?? "20px");
+  const tintVal = options.tint ?? "rgba(255, 255, 255, 0.65)";
+  const borderVal = options.border ?? "1px solid rgba(255, 255, 255, 0.75)";
+
+  return {
+    backdropFilter: `blur(${blurVal})`,
+    WebkitBackdropFilter: `blur(${blurVal})`,
+    backgroundColor: tintVal,
+    border: borderVal
+  };
+}
+
+/**
+ * Formats a style property value for direct DOM binding or SSR generation.
+ * Handles automatic unit resolution, dimension keywords, and custom CSS variables.
+ */
+export function formatStyleProp(prop: string, val: any): string {
+  if (val === null || val === undefined || val === "") return "";
+  if (typeof val === "number") {
+    if (val === 0 || UNITLESS_PROPERTIES.has(prop)) {
+      return String(val);
+    }
+    return `${val}px`;
+  }
+
+  const str = String(val).trim();
+  if (str in DIMENSION_KEYWORDS) {
+    const lowerProp = prop.toLowerCase();
+    if (str === "screen") {
+      if (lowerProp.includes("width")) return "100dvw";
+      return "100dvh";
+    }
+    return DIMENSION_KEYWORDS[str]!;
+  }
+
+  return str;
+}

package/src/template/index.ts

@@ -0,0 +1,4 @@
+export {
+  html,
+  template
+} from "./template";

package/src/template/template.ts

@@ -0,0 +1,126 @@
+import { insertChild, setAttribute } from "../dom/render";
+
+const templateCache = new Map<string, HTMLTemplateElement>();
+
+/**
+ * Cache and clone pre-parsed HTML template strings with native browser cloneNode(true)
+ */
+export function template<T extends HTMLElement = HTMLElement>(htmlString: string): () => T {
+  let templateEl = templateCache.get(htmlString);
+
+  if (!templateEl && typeof document !== "undefined") {
+    templateEl = document.createElement("template");
+    templateEl.innerHTML = htmlString.trim();
+    templateCache.set(htmlString, templateEl);
+  }
+
+  return () => {
+    if (!templateEl) {
+      const wrapper = document.createElement("div");
+      wrapper.innerHTML = htmlString.trim();
+      return wrapper.firstElementChild as T;
+    }
+    return templateEl.content.firstElementChild!.cloneNode(true) as T;
+  };
+}
+
+/**
+ * Tagged template literal for ultra-fast HTML string rendering with reactive signal bindings
+ */
+export function html(
+  strings: TemplateStringsArray,
+  ...values: any[]
+): HTMLElement | DocumentFragment {
+  const MARKER_PREFIX = "visage-bind-";
+  let htmlString = "";
+  const bindings: Array<{ id: string; value: any; isAttr: boolean; attrName?: string }> = [];
+
+  for (let i = 0; i < strings.length; i++) {
+    htmlString += strings[i];
+    if (i < values.length) {
+      const val = values[i];
+      const markerId = `${MARKER_PREFIX}${i}`;
+
+      const lastOpeningTag = htmlString.lastIndexOf("<");
+      const lastClosingTag = htmlString.lastIndexOf(">");
+
+      if (lastOpeningTag > lastClosingTag) {
+        const match = htmlString.match(/([a-zA-Z0-9_-]+)=["']?$/);
+        if (match?.[1]) {
+          const attrName = match[1];
+          bindings.push({ id: markerId, value: val, isAttr: true, attrName });
+          htmlString += `${markerId}`;
+        } else {
+          bindings.push({ id: markerId, value: val, isAttr: true });
+          htmlString += `data-visage-prop-${i}="${markerId}"`;
+        }
+      } else {
+        bindings.push({ id: markerId, value: val, isAttr: false });
+        htmlString += `<!--${markerId}-->`;
+      }
+    }
+  }
+
+  const clone = template(htmlString);
+  const root = clone();
+
+  for (const bind of bindings) {
+    if (bind.isAttr && bind.attrName) {
+      const targetEl = findElementWithAttributeValue(root, bind.attrName, bind.id);
+      if (targetEl) {
+        targetEl.removeAttribute(bind.attrName);
+        setAttribute(targetEl, bind.attrName, bind.value);
+      }
+    } else if (!bind.isAttr) {
+      const commentNode = findCommentNode(root, bind.id);
+      if (commentNode?.parentNode) {
+        insertChild(commentNode.parentNode, bind.value, commentNode);
+        commentNode.parentNode.removeChild(commentNode);
+      }
+    }
+  }
+
+  return root;
+}
+
+function findElementWithAttributeValue(
+  root: HTMLElement,
+  attrName: string,
+  value: string
+): HTMLElement | null {
+  if (root.getAttribute(attrName) === value) {
+    return root;
+  }
+  return root.querySelector(`[${attrName}="${value}"]`);
+}
+
+function findCommentNode(root: Node, text: string): Comment | null {
+  const iterator =
+    typeof document !== "undefined" && (document as any).createNodeIterator
+      ? (document as any).createNodeIterator(root, 128 /* SHOW_COMMENT */)
+      : null;
+
+  if (iterator) {
+    let node: Comment | null = iterator.nextNode();
+    while (node) {
+      if (node.nodeValue === text) {
+        return node;
+      }
+      node = iterator.nextNode();
+    }
+    return null;
+  }
+
+  const traverse = (node: Node): Comment | null => {
+    for (const child of node.childNodes || []) {
+      if (child.nodeType === 8 /* COMMENT */ && (child as any).data === text) {
+        return child as Comment;
+      }
+      const res = traverse(child);
+      if (res) return res;
+    }
+    return null;
+  };
+
+  return traverse(root);
+}