@luna_ui/luna 0.3.3 → 0.3.5

package/src/css/runtime.ts

@@ -0,0 +1,344 @@
+/**
+ * Development Mode CSS Runtime
+ *
+ * Provides runtime CSS injection for development mode.
+ * In production, this module should NOT be included.
+ *
+ * Features:
+ * - Dynamic CSS injection when rules are missing
+ * - Warning mechanism for missing CSS rules
+ * - Can be used as a fallback for hot-reload scenarios
+ */
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface CssRuntimeOptions {
+  /** Warn in console when generating CSS at runtime (default: true) */
+  warnOnGenerate?: boolean;
+  /** Style element ID (default: "luna-dev-css") */
+  styleId?: string;
+  /** Whether to log each rule generation (default: false) */
+  verbose?: boolean;
+}
+
+export interface CssRuntimeState {
+  /** Generated CSS rules */
+  rules: Map<string, string>;
+  /** Style element for injection */
+  styleEl: HTMLStyleElement | null;
+  /** Whether initialized */
+  initialized: boolean;
+}
+
+// =============================================================================
+// DJB2 Hash (must match registry.mbt and extract.ts)
+// =============================================================================
+
+function djb2Hash(s: string): number {
+  let hash = 5381;
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    hash = ((hash << 5) + hash + c) >>> 0;
+  }
+  return hash;
+}
+
+function toBase36(n: number): string {
+  const chars = "0123456789abcdefghijklmnopqrstuvwxyz";
+  n = n & 0xffffff;
+  if (n === 0) return "0";
+  let result = "";
+  while (n > 0) {
+    result = chars[n % 36] + result;
+    n = Math.floor(n / 36);
+  }
+  return result;
+}
+
+function hashClassName(decl: string): string {
+  const hash = djb2Hash(decl);
+  return "_" + toBase36(hash);
+}
+
+// =============================================================================
+// Runtime State
+// =============================================================================
+
+const state: CssRuntimeState = {
+  rules: new Map(),
+  styleEl: null,
+  initialized: false,
+};
+
+let options: CssRuntimeOptions = {
+  warnOnGenerate: true,
+  styleId: "luna-dev-css",
+  verbose: false,
+};
+
+// =============================================================================
+// Core Functions
+// =============================================================================
+
+/**
+ * Initialize the CSS runtime
+ */
+export function initCssRuntime(opts: CssRuntimeOptions = {}): void {
+  options = { ...options, ...opts };
+
+  if (typeof document === "undefined") {
+    // SSR mode - no-op
+    return;
+  }
+
+  if (state.initialized) {
+    return;
+  }
+
+  // Check if style element already exists
+  state.styleEl = document.getElementById(options.styleId!) as HTMLStyleElement;
+  if (!state.styleEl) {
+    state.styleEl = document.createElement("style");
+    state.styleEl.id = options.styleId!;
+    state.styleEl.setAttribute("data-luna-dev", "true");
+    document.head.appendChild(state.styleEl);
+  }
+
+  state.initialized = true;
+
+  if (options.verbose) {
+    console.log("[luna-css] Runtime initialized");
+  }
+}
+
+/**
+ * Check if a CSS class exists in stylesheets
+ */
+export function hasClass(className: string): boolean {
+  if (typeof document === "undefined") {
+    return true; // Assume exists in SSR
+  }
+
+  // Check our generated rules first
+  if (state.rules.has(className)) {
+    return true;
+  }
+
+  // Check all stylesheets
+  for (const sheet of document.styleSheets) {
+    try {
+      const rules = (sheet as CSSStyleSheet).cssRules;
+      for (const rule of rules) {
+        if (rule instanceof CSSStyleRule) {
+          if (rule.selectorText === `.${className}`) {
+            return true;
+          }
+        }
+      }
+    } catch {
+      // Cross-origin stylesheet, skip
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Generate CSS for a property:value declaration
+ * Returns the class name
+ */
+export function css(property: string, value: string): string {
+  const decl = `${property}:${value}`;
+  const className = hashClassName(decl);
+
+  if (!hasClass(className)) {
+    injectRule(className, decl);
+  }
+
+  return className;
+}
+
+/**
+ * Generate CSS for multiple property:value pairs
+ * Returns space-separated class names
+ */
+export function styles(pairs: [string, string][]): string {
+  return pairs.map(([p, v]) => css(p, v)).join(" ");
+}
+
+/**
+ * Generate CSS for pseudo-class
+ */
+export function on(pseudo: string, property: string, value: string): string {
+  const key = `${pseudo}:${property}:${value}`;
+  const className = hashClassName(key);
+
+  if (!hasClass(className)) {
+    injectPseudoRule(className, pseudo, property, value);
+  }
+
+  return className;
+}
+
+/**
+ * Hover shorthand
+ */
+export function hover(property: string, value: string): string {
+  return on(":hover", property, value);
+}
+
+/**
+ * Focus shorthand
+ */
+export function focus(property: string, value: string): string {
+  return on(":focus", property, value);
+}
+
+/**
+ * Active shorthand
+ */
+export function active(property: string, value: string): string {
+  return on(":active", property, value);
+}
+
+/**
+ * Media query CSS generation
+ */
+export function media(condition: string, property: string, value: string): string {
+  const key = `@media(${condition}):${property}:${value}`;
+  const className = hashClassName(key);
+
+  if (!hasClass(className)) {
+    injectMediaRule(className, condition, property, value);
+  }
+
+  return className;
+}
+
+/**
+ * Responsive breakpoint shortcuts
+ */
+export const at_sm = (p: string, v: string) => media("min-width:640px", p, v);
+export const at_md = (p: string, v: string) => media("min-width:768px", p, v);
+export const at_lg = (p: string, v: string) => media("min-width:1024px", p, v);
+export const at_xl = (p: string, v: string) => media("min-width:1280px", p, v);
+export const dark = (p: string, v: string) =>
+  media("prefers-color-scheme:dark", p, v);
+
+// =============================================================================
+// Internal Injection
+// =============================================================================
+
+function injectRule(className: string, decl: string): void {
+  if (!state.initialized) {
+    initCssRuntime();
+  }
+
+  const rule = `.${className}{${decl}}`;
+  state.rules.set(className, rule);
+
+  if (state.styleEl) {
+    state.styleEl.textContent += rule;
+  }
+
+  if (options.warnOnGenerate) {
+    console.warn(
+      `[luna-css] Generated at runtime: .${className} { ${decl} }`,
+      "\n  → Consider running 'luna css extract' to pre-generate CSS"
+    );
+  } else if (options.verbose) {
+    console.log(`[luna-css] ${rule}`);
+  }
+}
+
+function injectPseudoRule(
+  className: string,
+  pseudo: string,
+  property: string,
+  value: string
+): void {
+  if (!state.initialized) {
+    initCssRuntime();
+  }
+
+  const rule = `.${className}${pseudo}{${property}:${value}}`;
+  state.rules.set(className, rule);
+
+  if (state.styleEl) {
+    state.styleEl.textContent += rule;
+  }
+
+  if (options.warnOnGenerate) {
+    console.warn(
+      `[luna-css] Generated at runtime: .${className}${pseudo} { ${property}: ${value} }`,
+      "\n  → Consider running 'luna css extract' to pre-generate CSS"
+    );
+  } else if (options.verbose) {
+    console.log(`[luna-css] ${rule}`);
+  }
+}
+
+function injectMediaRule(
+  className: string,
+  condition: string,
+  property: string,
+  value: string
+): void {
+  if (!state.initialized) {
+    initCssRuntime();
+  }
+
+  const rule = `@media(${condition}){.${className}{${property}:${value}}}`;
+  state.rules.set(className, rule);
+
+  if (state.styleEl) {
+    state.styleEl.textContent += rule;
+  }
+
+  if (options.warnOnGenerate) {
+    console.warn(
+      `[luna-css] Generated at runtime: @media(${condition}) { .${className} { ${property}: ${value} } }`,
+      "\n  → Consider running 'luna css extract' to pre-generate CSS"
+    );
+  } else if (options.verbose) {
+    console.log(`[luna-css] ${rule}`);
+  }
+}
+
+// =============================================================================
+// Utility Functions
+// =============================================================================
+
+/**
+ * Get all generated CSS as a string
+ */
+export function getGeneratedCss(): string {
+  return Array.from(state.rules.values()).join("");
+}
+
+/**
+ * Get count of generated rules
+ */
+export function getGeneratedCount(): number {
+  return state.rules.size;
+}
+
+/**
+ * Reset the runtime state (for testing)
+ */
+export function resetRuntime(): void {
+  state.rules.clear();
+  if (state.styleEl) {
+    state.styleEl.textContent = "";
+  }
+  state.initialized = false;
+}
+
+/**
+ * Combine multiple class names
+ */
+export function combine(classes: string[]): string {
+  return classes.filter(Boolean).join(" ");
+}

package/src/css-optimizer/README.md

@@ -0,0 +1,353 @@
+# CSS Co-occurrence Optimizer
+
+A standalone, framework-agnostic library for optimizing CSS by merging frequently co-occurring classes. Works with HTML, React, Svelte, Vue, and any framework that uses class-based styling.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    CSS Optimizer                            │
+├─────────────────────────────────────────────────────────────┤
+│  Extractors          Core              Transformers         │
+│  ┌──────────┐    ┌──────────┐      ┌──────────────┐        │
+│  │ HTML     │    │ Pattern  │      │ HTML         │        │
+│  │ JSX/TSX  │───▶│ Analysis │─────▶│ JSX/TSX      │        │
+│  │ Svelte   │    │ + Merge  │      │ Svelte       │        │
+│  │ Custom   │    └──────────┘      │ Custom       │        │
+│  └──────────┘                      └──────────────┘        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+- **Extractors**: Pluggable class extraction from different source formats
+- **Core**: Framework-agnostic pattern analysis and CSS generation
+- **Transformers**: Pluggable output transformation for different formats
+
+## Installation
+
+```bash
+npm install @luna_ui/luna
+```
+
+## Quick Start
+
+### Framework-Agnostic Usage (Recommended)
+
+```typescript
+import {
+  optimizeCore,
+  htmlExtractor,
+  htmlTransformer,
+} from "@luna_ui/luna/css-optimizer";
+
+// 1. Extract class usages from your source files
+const usages = htmlExtractor.extract(html, { classPrefix: "_" });
+
+// 2. Build class-to-declaration mapping
+const classToDecl = new Map([
+  ["_flex", "display:flex"],
+  ["_gap", "gap:1rem"],
+  ["_p4", "padding:1rem"],
+]);
+
+// 3. Optimize
+const result = optimizeCore(usages, css, classToDecl, {
+  minFrequency: 2,
+  maxPatternSize: 5,
+});
+
+// 4. Transform output
+const optimizedHtml = htmlTransformer.transform(html, result.mergeMap);
+
+console.log(result.css);        // Optimized CSS
+console.log(optimizedHtml);     // Transformed HTML
+console.log(result.stats);      // { mergedPatterns, estimatedBytesSaved, ... }
+```
+
+### React/JSX Usage
+
+```typescript
+import {
+  optimizeCore,
+  jsxExtractor,
+  jsxTransformer,
+} from "@luna_ui/luna/css-optimizer";
+
+// Extract from JSX
+const usages = jsxExtractor.extract(jsxCode);
+
+// ... optimize ...
+
+// Transform JSX
+const optimizedJsx = jsxTransformer.transform(jsxCode, result.mergeMap);
+```
+
+### Svelte Usage
+
+```typescript
+import {
+  optimizeCore,
+  svelteExtractor,
+  svelteTransformer,
+} from "@luna_ui/luna/css-optimizer";
+
+// Extract from Svelte (preserves {expressions})
+const usages = svelteExtractor.extract(svelteCode);
+
+// ... optimize ...
+
+// Transform Svelte (preserves {expressions})
+const optimizedSvelte = svelteTransformer.transform(svelteCode, result.mergeMap);
+```
+
+### Multi-Framework Projects
+
+```typescript
+import {
+  optimizeCore,
+  multiExtractor,
+  multiTransformer,
+} from "@luna_ui/luna/css-optimizer";
+
+// Extract from multiple file types
+const files = [
+  { content: htmlCode, path: "index.html" },
+  { content: reactCode, path: "app.tsx" },
+  { content: svelteCode, path: "widget.svelte" },
+];
+
+const usages = multiExtractor.extractFromFiles(files);
+
+// ... optimize ...
+
+// Transform all files
+const transformedFiles = multiTransformer.transformFiles(files, result.mergeMap);
+```
+
+### Luna-Specific Convenience API
+
+For Luna projects, use the simplified API:
+
+```typescript
+import { optimizeCss, optimizeHtml } from "@luna_ui/luna/css-optimizer";
+
+// Luna uses declaration -> className mapping
+const mapping = {
+  "display:flex": "_flex",
+  "gap:1rem": "_gap",
+};
+
+const result = optimizeCss(css, html, mapping, {
+  minFrequency: 2,
+});
+
+const optimizedHtml = optimizeHtml(html, result.mergeMap);
+```
+
+## API Reference
+
+### Core Functions
+
+#### `optimizeCore(usages, css, classToDeclaration, options?)`
+
+Framework-agnostic core optimizer.
+
+```typescript
+function optimizeCore(
+  usages: ClassUsage[],
+  css: string,
+  classToDeclaration: Map<string, string>,
+  options?: CoreOptimizeOptions
+): CoreOptimizeResult;
+```
+
+#### `applyMergeToClasses(classes, mergeMap, classPrefix?)`
+
+Apply merge map to a class array (useful for runtime optimization).
+
+```typescript
+function applyMergeToClasses(
+  classes: string[],
+  mergeMap: Map<string, string>,
+  classPrefix?: string
+): string[];
+```
+
+### Extractors
+
+All extractors implement the `ClassExtractor` interface:
+
+```typescript
+interface ClassExtractor {
+  name: string;
+  extract(content: string, options?: ExtractorOptions): ClassUsage[];
+}
+
+interface ExtractorOptions {
+  classPrefix?: string;  // Filter classes by prefix (default: "_")
+  minClasses?: number;   // Minimum classes per element (default: 2)
+  source?: string;       // Source identifier for debugging
+}
+```
+
+| Extractor | Description | Import |
+|-----------|-------------|--------|
+| `HtmlExtractor` | Extracts from `class="..."` | `htmlExtractor` |
+| `JsxExtractor` | Extracts from `className="..."` | `jsxExtractor` |
+| `SvelteExtractor` | Extracts from `class="..."`, preserves `{expr}` | `svelteExtractor` |
+| `MultiExtractor` | Auto-selects by file extension | `multiExtractor` |
+
+### Transformers
+
+All transformers implement the `ClassTransformer` interface:
+
+```typescript
+interface ClassTransformer {
+  name: string;
+  transform(
+    content: string,
+    mergeMap: Map<string, string>,
+    options?: TransformerOptions
+  ): string;
+}
+
+interface TransformerOptions {
+  classPrefix?: string;  // Class prefix for identifying mergeable classes
+}
+```
+
+| Transformer | Description | Import |
+|-------------|-------------|--------|
+| `HtmlTransformer` | Transforms `class="..."` | `htmlTransformer` |
+| `JsxTransformer` | Transforms `className="..."` | `jsxTransformer` |
+| `SvelteTransformer` | Transforms `class="..."`, preserves `{expr}` | `svelteTransformer` |
+| `MultiTransformer` | Auto-selects by file extension | `multiTransformer` |
+
+### Options
+
+```typescript
+interface CoreOptimizeOptions {
+  minFrequency?: number;     // Min occurrences to merge (default: 2)
+  maxPatternSize?: number;   // Max classes per pattern (default: 5)
+  pretty?: boolean;          // Pretty-print CSS (default: false)
+  verbose?: boolean;         // Enable logging (default: false)
+}
+```
+
+### Custom Extractors
+
+```typescript
+import { ClassExtractor, ClassUsage } from "@luna_ui/luna/css-optimizer";
+
+class VueExtractor implements ClassExtractor {
+  name = "vue";
+
+  extract(content: string, options = {}): ClassUsage[] {
+    // Parse Vue SFC template section
+    // Return array of ClassUsage objects
+  }
+}
+
+// Register with MultiExtractor
+multiExtractor.register("vue", new VueExtractor());
+```
+
+## Build Tool Integration
+
+### Vite Plugin (Luna)
+
+```typescript
+// vite.config.ts
+import { lunaCss } from "@luna_ui/luna/vite-plugin";
+
+export default {
+  plugins: [
+    lunaCss({
+      src: ["src"],
+      experimental: {
+        optimize: true,
+        optimizeMinFrequency: 2,
+        optimizeMaxPatternSize: 5,
+      },
+    }),
+  ],
+};
+```
+
+### Generic Build Pipeline
+
+```typescript
+// build.ts
+import {
+  optimizeCore,
+  multiExtractor,
+  multiTransformer,
+} from "@luna_ui/luna/css-optimizer";
+import { readFileSync, writeFileSync } from "fs";
+import { glob } from "glob";
+
+// 1. Collect source files
+const files = glob.sync("src/**/*.{html,jsx,tsx,svelte}").map((path) => ({
+  path,
+  content: readFileSync(path, "utf-8"),
+}));
+
+// 2. Extract class usages
+const usages = multiExtractor.extractFromFiles(files);
+
+// 3. Build class-to-declaration map (from your CSS tool)
+const classToDecl = buildClassMap(css);
+
+// 4. Optimize
+const result = optimizeCore(usages, css, classToDecl);
+
+// 5. Write optimized CSS
+writeFileSync("dist/styles.css", result.css);
+
+// 6. Transform source files
+const transformed = multiTransformer.transformFiles(files, result.mergeMap);
+for (const file of transformed) {
+  writeFileSync(`dist/${file.path}`, file.content);
+}
+```
+
+## How It Works
+
+### Pattern Mining
+
+1. **Extract**: Parse source files to find class attribute values
+2. **Analyze**: Count co-occurrence frequency of class combinations
+3. **Mine**: Find patterns (pairs, triples, etc.) that meet frequency threshold
+4. **Filter**: Remove subsumed patterns (subsets with similar frequency)
+5. **Merge**: Generate combined CSS rules with deterministic class names
+
+### Savings Estimation
+
+```
+HTML savings = (classCount - 1) * avgClassNameLength * frequency
+CSS savings  = (classCount - 1) * avgRuleSize
+```
+
+### Deterministic Naming
+
+Merged classes use DJB2 hash of sorted declarations:
+```
+_flex _gap _p4 → _m2rld5
+```
+
+This ensures consistent naming across builds.
+
+## Limitations
+
+- Regex-based extraction (not full AST)
+- Only static class values (not computed/dynamic)
+- Pseudo-class/media rules preserved but not merged
+- Single-quoted class attributes not supported (use double quotes)
+
+## Future Improvements
+
+- [ ] AST-based extraction for React/Svelte
+- [ ] Dynamic class detection
+- [ ] Pseudo-class pattern merging
+- [ ] Source map generation
+- [ ] Webpack plugin
+- [ ] CLI tool