@numbered/docs-to-context 0.3.0 → 0.4.0

package/docs/layout/scripts/pixels_to_columns.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+"""
+Convert pixel values to Tailwind CSS grid column classes.
+
+Compatible with @numbered/tailwind-fluid-layout-system.
+
+Usage:
+    python pixels_to_columns.py <pixels> [--columns N] [--mockup N] [--gutter N] [--margin N]
+
+Examples:
+    # Desktop: 330px element in 24-column grid
+    python pixels_to_columns.py 330 --columns 24 --mockup 1440 --gutter 24 --margin 24
+
+    # Mobile: 150px element in 6-column grid
+    python pixels_to_columns.py 150 --columns 6 --mockup 375 --gutter 12 --margin 12
+"""
+
+import argparse
+import json
+import sys
+
+
+def pixels_to_columns(
+    pixels: float,
+    grid_columns: int = 24,
+    mockup_width: int = 1440,
+    gutter: int = 24,
+    margin: int = 24
+) -> dict:
+    """
+    Convert pixel value to Tailwind grid column span class.
+
+    Args:
+        pixels: The pixel value to convert
+        grid_columns: Number of grid columns (6 mobile, 24 desktop)
+        mockup_width: Total mockup width in pixels (375 mobile, 1440 desktop)
+        gutter: Gutter size between columns in pixels
+        margin: Outer margins in pixels
+
+    Returns:
+        Dictionary with className, columns, actualWidth, pixelDifference, and gridConfig
+    """
+    # Calculate available width for content (mockup width minus margins)
+    content_width = mockup_width - (2 * margin)
+
+    # Calculate column width: N columns have (N-1) gutters between them
+    # content_width = (grid_columns * column_width) + ((grid_columns - 1) * gutter)
+    # Solving for column_width:
+    total_gutter_space = (grid_columns - 1) * gutter
+    total_column_space = content_width - total_gutter_space
+    column_width = total_column_space / grid_columns
+
+    # Build grid config once (DRY)
+    grid_config = {
+        "columns": grid_columns,
+        "mockupWidth": mockup_width,
+        "gutter": gutter,
+        "margin": margin,
+        "columnWidth": round(column_width),
+        "contentWidth": round(content_width)
+    }
+
+    def span_width(n, suffix=""):
+        """Calculate width for span-w-N with optional suffix."""
+        # Base: N columns + (N-1) gutters
+        base = (n * column_width) + ((n - 1) * gutter)
+        if suffix == "-wide":
+            return base + gutter
+        elif suffix == "-wider":
+            return base + (gutter * 2)
+        return base
+
+    # Check if value is less than 1 column - use gutter-based matching
+    if pixels < column_width:
+        # Gutter multiples to check: 0.5, 1, 1.5, 2, 2.5, 3, 4, 5, 6
+        gutter_multiples = [0.5, 1, 1.5, 2, 2.5, 3, 4, 5, 6]
+        best_gutter = None
+        best_gutter_diff = float('inf')
+
+        for mult in gutter_multiples:
+            gutter_px = gutter * mult
+            diff = abs(gutter_px - pixels)
+            if diff < best_gutter_diff:
+                best_gutter_diff = diff
+                best_gutter = {"mult": mult, "px": gutter_px}
+
+        # Format multiplier: 0.5 -> "0.5", 1 -> "1", 1.5 -> "1.5", 2 -> "2"
+        mult = best_gutter["mult"]
+        if mult == int(mult):
+            mult_str = str(int(mult))
+        else:
+            mult_str = str(mult)
+
+        return {
+            "className": f"gutter-gap-{mult_str}",
+            "columns": 0,
+            "gutters": mult,
+            "actualWidth": round(best_gutter["px"]),
+            "pixelDifference": round(best_gutter["px"] - pixels),
+            "gridConfig": grid_config
+        }
+
+    # Find best matching span for values >= 1 column
+    best_match = None
+    best_diff = float('inf')
+    exact_match = False
+
+    for n in range(1, grid_columns + 1):
+        if exact_match:
+            break
+        for suffix in ["", "-wide", "-wider"]:
+            width = span_width(n, suffix)
+            diff = abs(width - pixels)
+            if diff < best_diff:
+                best_diff = diff
+                best_match = {
+                    "columns": n,
+                    "suffix": suffix,
+                    "width": width
+                }
+            # Early exit if exact match
+            if diff == 0:
+                exact_match = True
+                break
+
+    class_name = f"span-w-{best_match['columns']}{best_match['suffix']}"
+    actual_width = best_match['width']
+
+    return {
+        "className": class_name,
+        "columns": best_match['columns'],
+        "actualWidth": round(actual_width),
+        "pixelDifference": round(actual_width - pixels),
+        "gridConfig": grid_config
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Convert pixel values to Tailwind grid column classes",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Grid Presets:
+  Desktop: --columns 24 --mockup 1440 --gutter 24 --margin 24
+  Mobile:  --columns 6  --mockup 375  --gutter 12 --margin 12
+
+Examples:
+  %(prog)s 330 --columns 24 --mockup 1440 --gutter 24 --margin 24
+  %(prog)s 150 --columns 6 --mockup 375 --gutter 12 --margin 12
+        """
+    )
+
+    parser.add_argument("pixels", type=float, help="Pixel value to convert")
+    parser.add_argument("--columns", type=int, default=24, help="Number of grid columns (default: 24)")
+    parser.add_argument("--mockup", type=int, default=1440, help="Mockup width in pixels (default: 1440)")
+    parser.add_argument("--gutter", type=int, default=24, help="Gutter size in pixels (default: 24)")
+    parser.add_argument("--margin", type=int, default=24, help="Outer margin in pixels (default: 24)")
+    parser.add_argument("--json", action="store_true", help="Output full JSON result")
+
+    args = parser.parse_args()
+
+    if args.pixels <= 0:
+        print("Error: pixels must be positive", file=sys.stderr)
+        sys.exit(1)
+
+    result = pixels_to_columns(
+        pixels=args.pixels,
+        grid_columns=args.columns,
+        mockup_width=args.mockup,
+        gutter=args.gutter,
+        margin=args.margin
+    )
+
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        # Concise output for quick use
+        diff = result["pixelDifference"]
+        diff_str = f"+{diff}px" if diff > 0 else f"{diff}px" if diff < 0 else "exact"
+        print(f"{result['className']} ({result['actualWidth']}px, {diff_str})")
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@numbered/docs-to-context",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"description": "Generate project docs (component APIs, design system, architecture) and inject index into CLAUDE.md",
 	"bin": {
 		"docs-to-context": "scripts/generate.ts"
@@ -8,6 +8,7 @@
 	"files": [
 		"scripts/*.ts",
 		"docs/**/*.mdx",
+		"docs/**/*.py",
 		"README.md"
 	],
 	"scripts": {

package/scripts/inject.ts

@@ -23,14 +23,16 @@ const MARKER_PATTERN = new RegExp(
 )
 const CORE_DOCS_ROOT = 'docs'
 const CONTEXT_ROOT = '.context'
-const REGENERATE_CMD = 'bunx @numbered/docs-to-context'
+const REGENERATE_CMD = 'bunx @numbered/docs-to-context@latest'
 
 // ── Types ──────────────────────────────────────────────────────────────
 
 interface CoreDocs {
 	frontend: string[]
 	entities: string[]
+	entitiesRoot: string
 	bestPractices: string[]
+	layout: string[]
 }
 
 // ── Helpers ────────────────────────────────────────────────────────────
@@ -94,11 +96,48 @@ function copyBestPractices(projectRoot: string, platform: string): string[] {
 	return copied
 }
 
+// ── Layout docs copy ────────────────────────────────────────────────
+
+function copyLayout(projectRoot: string): string[] {
+	const bundledDir = resolve(import.meta.dir, '..', 'docs', 'layout')
+	if (!isDir(bundledDir)) return []
+
+	const destDir = join(projectRoot, CONTEXT_ROOT, 'layout')
+	mkdirSync(destDir, { recursive: true })
+
+	const mdFiles = walkDir(bundledDir, ['.md', '.mdx'])
+	const copied: string[] = []
+
+	for (const src of mdFiles) {
+		const name = src.slice(src.lastIndexOf('/') + 1)
+		copyFileSync(src, join(destDir, name))
+		copied.push(`layout/${name}`)
+	}
+
+	// Copy scripts
+	const scriptsDir = join(bundledDir, 'scripts')
+	if (isDir(scriptsDir)) {
+		const destScriptsDir = join(projectRoot, CONTEXT_ROOT, 'scripts')
+		mkdirSync(destScriptsDir, { recursive: true })
+		const pyFiles = walkDir(scriptsDir, ['.py'])
+		for (const src of pyFiles) {
+			const name = src.slice(src.lastIndexOf('/') + 1)
+			copyFileSync(src, join(destScriptsDir, name))
+		}
+	}
+
+	if (copied.length) {
+		log.success(`Copied ${copied.length} layout doc(s)`)
+	}
+
+	return copied
+}
+
 // ── Core docs discovery ────────────────────────────────────────────────
 
-function discoverCoreDocs(projectRoot: string, bestPractices: string[]): CoreDocs {
+function discoverCoreDocs(projectRoot: string, bestPractices: string[], layout: string[]): CoreDocs {
 	const docsDir = join(projectRoot, CORE_DOCS_ROOT)
-	const result: CoreDocs = { frontend: [], entities: [], bestPractices }
+	const result: CoreDocs = { frontend: [], entities: [], entitiesRoot: '', bestPractices, layout }
 
 	if (!isDir(docsDir)) return result
 
@@ -110,7 +149,8 @@ function discoverCoreDocs(projectRoot: string, bestPractices: string[]): CoreDoc
 	// Entities: architecture specs
 	const archDir = join(docsDir, 'specs', 'architecture')
 	if (isDir(archDir)) {
-		result.entities = walkDir(archDir, ['.md', '.mdx']).map((f) => relative(docsDir, f))
+		result.entitiesRoot = relative(docsDir, archDir)
+		result.entities = walkDir(archDir, ['.md', '.mdx']).map((f) => relative(archDir, f))
 	}
 
 	return result
@@ -124,11 +164,16 @@ function buildComponentLines(names: string[]): string[] {
 		`[Component Index]|root: ${root}`,
 		'|IMPORTANT: Read component MDX before using any component',
 		`|components:{${names.join(',')}}`,
-		`|If ${root} is missing, run: ${REGENERATE_CMD}`,
+		`|If ./${CONTEXT_ROOT} is missing, run: ${REGENERATE_CMD}`,
 	]
 }
 
-function buildIndexBlock(indexPath: string, coreDocs: CoreDocs | null): string | null {
+const PLATFORM_LABEL: Record<string, string> = {
+	nextjs: 'React & Next.js',
+	shopify: 'Liquid & Alpine.js',
+}
+
+function buildIndexBlock(indexPath: string, coreDocs: CoreDocs | null, platform?: string): string | null {
 	const indexContent = readFileSync(indexPath, 'utf-8').trim()
 
 	const names: string[] = []
@@ -145,17 +190,28 @@ function buildIndexBlock(indexPath: string, coreDocs: CoreDocs | null): string |
 
 	// Frontend
 	if (coreDocs?.frontend.length) {
-		lines.push(`|[Frontend]|root: ${docsRoot}`)
+		lines.push(`|[Frontend — Design System & Grid]|root: ${docsRoot}`)
+		lines.push('|IMPORTANT: Read before any styling, layout, or spacing work')
 		lines.push(`|frontend:{${coreDocs.frontend.join(',')}}`)
 	}
 
 	// Best Practices
 	if (coreDocs?.bestPractices.length) {
 		const contextRoot = `./${CONTEXT_ROOT}`
+		const label = (platform && PLATFORM_LABEL[platform]) || ''
 		const fileNames = coreDocs.bestPractices.map((p) => p.slice(p.lastIndexOf('/') + 1))
-		lines.push(`|[Best Practices]|root: ${contextRoot}`)
+		lines.push(`|[Best Practices${label ? ` — ${label}` : ''}]|root: ${contextRoot}`)
 		lines.push(`|best-practices:{${fileNames.join(',')}}`)
-		lines.push('|IMPORTANT: Read best-practices/README.mdx first — it indexes all patterns by category and impact')
+		lines.push(`|IMPORTANT: ${label || 'Performance'} patterns — read best-practices/README.mdx first, it indexes all patterns by category and impact`)
+	}
+
+	// Layout
+	if (coreDocs?.layout.length) {
+		const contextRoot = `./${CONTEXT_ROOT}`
+		const fileNames = coreDocs.layout.map((p) => p.slice(p.lastIndexOf('/') + 1))
+		lines.push(`|[Layout & Integration]|root: ${contextRoot}`)
+		lines.push(`|IMPORTANT: Read before implementing any layout — convert pixels to columns with .context/scripts/pixels_to_columns.py`)
+		lines.push(`|layout:{${fileNames.join(',')}}`)
 	}
 
 	// Components (always present)
@@ -163,9 +219,11 @@ function buildIndexBlock(indexPath: string, coreDocs: CoreDocs | null): string |
 
 	// Entities (grouped by directory)
 	if (coreDocs?.entities.length) {
-		lines.push(`|[Entities]|root: ${docsRoot}`)
+		const entRoot = coreDocs.entitiesRoot ? `${docsRoot}/${coreDocs.entitiesRoot}` : docsRoot
+		lines.push(`|[Entities]|root: ${entRoot}`)
 		for (const [dirPath, files] of groupByDir(coreDocs.entities)) {
-			lines.push(`|${dirPath}:{${files.join(',')}}`)
+			const prefix = dirPath === '.' ? '' : `${dirPath}:`
+			lines.push(`|${prefix}{${files.join(',')}}`)
 		}
 	}
 
@@ -241,11 +299,14 @@ export function inject(opts: InjectOptions) {
 	// Copy best practices if platform is known
 	const bestPractices = opts.platform ? copyBestPractices(root, opts.platform) : []
 
-	const coreDocs = discoverCoreDocs(root, bestPractices)
-	const total = coreDocs.frontend.length + coreDocs.entities.length + coreDocs.bestPractices.length
+	// Copy layout docs (always)
+	const layout = copyLayout(root)
+
+	const coreDocs = discoverCoreDocs(root, bestPractices, layout)
+	const total = coreDocs.frontend.length + coreDocs.entities.length + coreDocs.bestPractices.length + coreDocs.layout.length
 	if (total) log.info(`Found ${total} core doc(s)`)
 
-	const block = buildIndexBlock(indexPath, total ? coreDocs : null)
+	const block = buildIndexBlock(indexPath, total ? coreDocs : null, opts.platform)
 	if (!block) {
 		log.error('INDEX file is empty, nothing to inject.')
 		process.exit(1)