@bookklik/senangstart-css 0.2.4 → 0.2.6

package/.agent/skills/jit-engine/examples/add-visual-utility.js

@@ -0,0 +1,117 @@
+/**
+ * Example: Adding a Simple Visual Utility
+ * 
+ * This example shows how to add a new 'glow' utility that adds
+ * a colored shadow effect to elements.
+ * 
+ * Usage: visual="glow:primary glow:blue-500"
+ */
+
+// ================================================
+// Step 1: Add to Definition File
+// ================================================
+// File: src/definitions/visual.js or create visual-glow.js
+
+export const glowDefinition = {
+  name: 'glow',
+  property: 'box-shadow',
+  category: 'visual',
+  attribute: 'visual',
+  description: 'Adds a colored glow effect around the element',
+  descriptionMs: 'Menambah kesan cahaya berwarna di sekeliling elemen',
+  syntax: 'glow:<color>',
+  values: [
+    { name: 'primary', value: '0 0 20px var(--ss-color-primary)', description: 'Primary color glow' },
+    { name: 'secondary', value: '0 0 20px var(--ss-color-secondary)', description: 'Secondary color glow' },
+    { name: 'none', value: 'none', description: 'Remove glow' }
+  ],
+  examples: [
+    { code: 'visual="glow:primary"', description: 'Blue glow effect' },
+    { code: 'visual="glow:secondary"', description: 'Purple glow effect' },
+    { code: 'visual="hover:glow:primary"', description: 'Glow on hover' }
+  ],
+  notes: 'Accepts any color from the color palette'
+};
+
+// ================================================
+// Step 2: Add Handler to JIT Engine
+// ================================================
+// File: src/cdn/senangstart-engine.js
+// Add in generateVisualRule() function:
+
+/*
+if (prop === 'glow') {
+  if (value === 'none') {
+    return 'box-shadow: none';
+  }
+  const color = config.theme.colors[value];
+  if (color) {
+    return `box-shadow: 0 0 20px ${color}`;
+  }
+  // Arbitrary color support
+  if (value.startsWith('[') && value.endsWith(']')) {
+    return `box-shadow: 0 0 20px ${value.slice(1, -1)}`;
+  }
+}
+*/
+
+// ================================================
+// Step 3: Add Handler to CSS Generator
+// ================================================
+// File: src/compiler/generators/css.js
+// Add in generateVisualRule() function (same logic as JIT):
+
+/*
+if (prop === 'glow') {
+  if (value === 'none') {
+    return 'box-shadow: none';
+  }
+  const color = config.theme.colors[value];
+  if (color) {
+    return `box-shadow: 0 0 20px ${color}`;
+  }
+  if (token.isArbitrary) {
+    return `box-shadow: 0 0 20px ${sanitizeArbitraryValue(value)}`;
+  }
+}
+*/
+
+// ================================================
+// Step 4: Write Test
+// ================================================
+// File: tests/unit/compiler/generators/glow.test.js
+
+/*
+import { test, describe } from 'node:test';
+import assert from 'node:assert';
+import { generateVisualRule } from '../../../../src/compiler/generators/css.js';
+
+const mockConfig = {
+  theme: {
+    colors: {
+      'primary': '#3B82F6',
+      'secondary': '#8B5CF6'
+    }
+  }
+};
+
+describe('glow utility', () => {
+  test('generates glow with primary color', () => {
+    const token = { property: 'glow', value: 'primary', attrType: 'visual' };
+    const result = generateVisualRule(token, mockConfig);
+    assert.strictEqual(result, 'box-shadow: 0 0 20px #3B82F6');
+  });
+
+  test('generates glow:none', () => {
+    const token = { property: 'glow', value: 'none', attrType: 'visual' };
+    const result = generateVisualRule(token, mockConfig);
+    assert.strictEqual(result, 'box-shadow: none');
+  });
+});
+*/
+
+// ================================================
+// Step 5: Generate Documentation
+// ================================================
+// Run: npm run docs:generate
+// This creates docs/reference/visual/glow.md automatically

package/.agent/skills/jit-engine/examples/scale-based-utilities.js

@@ -0,0 +1,130 @@
+/**
+ * Example: Handling Scale-Based Utilities
+ * 
+ * This example shows patterns for utilities that use theme scales
+ * like spacing, colors, or custom scales.
+ */
+
+// ================================================
+// Pattern 1: Using Existing Scale (spacing)
+// ================================================
+
+/*
+// In generateVisualRule():
+if (prop === 'outline-offset') {
+  const space = config.theme.spacing[value];
+  if (space) {
+    return `outline-offset: ${space}`;
+  }
+  // Fallback to raw value for arbitrary
+  if (token.isArbitrary) {
+    return `outline-offset: ${value}`;
+  }
+}
+*/
+
+// ================================================
+// Pattern 2: Adding a New Custom Scale
+// ================================================
+
+// Step 1: Add scale to defaultConfig in senangstart-engine.js
+/*
+const defaultConfig = {
+  theme: {
+    // ... existing scales
+    blur: {
+      'none': '0',
+      'tiny': '2px',
+      'small': '4px',
+      'medium': '8px',
+      'big': '16px',
+      'giant': '24px'
+    }
+  }
+};
+*/
+
+// Step 2: Generate CSS variables in generateCSSVariables()
+/*
+Object.entries(config.theme.blur).forEach(([name, value]) => {
+  vars += `  --ss-blur-${name}: ${value};\n`;
+});
+*/
+
+// Step 3: Use in generator
+/*
+if (prop === 'blur') {
+  const blur = config.theme.blur[value];
+  if (blur) {
+    return `filter: blur(${blur})`;
+  }
+}
+*/
+
+// ================================================
+// Pattern 3: Directional Utilities
+// ================================================
+
+/*
+// Handle p-t, p-r, p-b, p-l, p-x, p-y patterns
+if (prop.startsWith('p-')) {
+  const space = config.theme.spacing[value];
+  if (!space) return null;
+  
+  const dir = prop.substring(2);
+  switch (dir) {
+    case 't': return `padding-top: ${space}`;
+    case 'r': return `padding-right: ${space}`;
+    case 'b': return `padding-bottom: ${space}`;
+    case 'l': return `padding-left: ${space}`;
+    case 'x': return `padding-left: ${space}; padding-right: ${space}`;
+    case 'y': return `padding-top: ${space}; padding-bottom: ${space}`;
+  }
+}
+*/
+
+// ================================================
+// Pattern 4: Negative Values
+// ================================================
+
+/*
+// Handle negative margin: m-t:-small
+if (prop.startsWith('m-') || prop === 'm') {
+  let isNegative = false;
+  let val = value;
+  
+  if (value.startsWith('-')) {
+    isNegative = true;
+    val = value.substring(1);
+  }
+  
+  const space = config.theme.spacing[val];
+  if (space) {
+    const finalValue = isNegative ? `-${space}` : space;
+    return `margin-${direction}: ${finalValue}`;
+  }
+}
+*/
+
+// ================================================
+// Pattern 5: Tailwind Compatibility (tw- prefix)
+// ================================================
+
+/*
+// In defaultConfig, add tw-* values for Tailwind compatibility
+const defaultConfig = {
+  theme: {
+    spacing: {
+      // Native semantic values
+      'none': '0px',
+      'small': '8px',
+      // Tailwind compatibility values
+      'tw-0': '0px',
+      'tw-1': '0.25rem',
+      'tw-2': '0.5rem',
+      'tw-4': '1rem',
+      // ...
+    }
+  }
+};
+*/

package/.agent/skills/jit-engine/examples/state-responsive-handling.js

@@ -0,0 +1,177 @@
+/**
+ * Example: State and Responsive Handling
+ * 
+ * This example shows how states (hover, focus) and 
+ * responsive prefixes (mob, tab) work in the engine.
+ */
+
+// ================================================
+// State Handling in JIT Engine
+// ================================================
+
+/*
+// States are parsed in processTokens() before calling generators
+function processTokens(attrValue, attrType) {
+  const tokens = attrValue.trim().split(/\s+/);
+  
+  for (const token of tokens) {
+    const parts = token.split(':');
+    let state = null;
+    let breakpoint = null;
+    let propIdx = 0;
+    
+    // Check for breakpoint prefix (mob:, tab:, etc.)
+    if (BREAKPOINTS.includes(parts[0])) {
+      breakpoint = parts[0];
+      propIdx++;
+    }
+    
+    // Check for state prefix (hover:, focus:, etc.)
+    if (STATES.includes(parts[propIdx])) {
+      state = parts[propIdx];
+      propIdx++;
+    }
+    
+    // Rest is property:value
+    const property = parts[propIdx];
+    const value = parts.slice(propIdx + 1).join(':');
+    
+    generateRule({ property, value, state, breakpoint });
+  }
+}
+*/
+
+// ================================================
+// Generating State-Based CSS
+// ================================================
+
+/*
+function generateSelector(rawToken, attrType, state) {
+  // Escape special characters in selector
+  const escaped = rawToken.replace(/:/g, '\\:');
+  const baseSelector = `[${attrType}~="${rawToken}"]`;
+  
+  if (state) {
+    // Add pseudo-class
+    return `${baseSelector}:${state}`;
+  }
+  
+  return baseSelector;
+}
+
+// Example output:
+// [visual~="hover:bg:blue-500"]:hover { background-color: #3B82F6 }
+*/
+
+// ================================================
+// Responsive Breakpoint Handling
+// ================================================
+
+/*
+function wrapWithMediaQuery(css, breakpoint, config) {
+  if (!breakpoint) return css;
+  
+  const minWidth = config.theme.screens[breakpoint];
+  return `@media (min-width: ${minWidth}) {\n  ${css}\n}`;
+}
+
+// Example output:
+// @media (min-width: 768px) {
+//   [layout~="tab:flex"] { display: flex }
+// }
+*/
+
+// ================================================
+// Group Hover (Parent-Child States)
+// ================================================
+
+/*
+// group-hover: requires parent with 'group' class
+if (state === 'group-hover') {
+  // Selector: .group:hover [visual~="group-hover:bg:blue-500"]
+  return `.group:hover ${baseSelector}`;
+}
+
+// Usage:
+// <div layout="group">
+//   <span visual="group-hover:text:blue-500">Hover parent to change me</span>
+// </div>
+*/
+
+// ================================================
+// Dark Mode State
+// ================================================
+
+/*
+function getDarkModeSelector(config) {
+  if (config.darkMode === 'media') {
+    return '@media (prefers-color-scheme: dark)';
+  }
+  return '.dark';  // Selector mode
+}
+
+// For dark: state
+if (state === 'dark') {
+  if (config.darkMode === 'media') {
+    return `@media (prefers-color-scheme: dark) {\n  ${baseSelector} { ${css} }\n}`;
+  } else {
+    return `.dark ${baseSelector} { ${css} }`;
+  }
+}
+*/
+
+// ================================================
+// Combining States and Breakpoints
+// ================================================
+
+/*
+// Token: tab:hover:bg:blue-500
+// Breakdown:
+//   breakpoint: 'tab' (768px)
+//   state: 'hover'
+//   property: 'bg'
+//   value: 'blue-500'
+
+// Output:
+// @media (min-width: 768px) {
+//   [visual~="tab:hover:bg:blue-500"]:hover {
+//     background-color: #3B82F6
+//   }
+// }
+*/
+
+// ================================================
+// Available States (from constants.js)
+// ================================================
+
+const STATES = [
+  'hover',
+  'focus',
+  'active',
+  'focus-visible',
+  'focus-within',
+  'disabled',
+  'group-hover',
+  'first',
+  'last',
+  'odd',
+  'even',
+  'dark'
+];
+
+// ================================================
+// Available Breakpoints (from constants.js)
+// ================================================
+
+const BREAKPOINTS = [
+  'mob',   // 480px  (mobile)
+  'tab',   // 768px  (tablet)
+  'lap',   // 1024px (laptop)
+  'desk',  // 1280px (desktop)
+  // Tailwind compat
+  'tw-sm', // 640px
+  'tw-md', // 768px
+  'tw-lg', // 1024px
+  'tw-xl', // 1280px
+  'tw-2xl' // 1536px
+];

package/.agent/skills/senangstart-architecture/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: SenangStart CSS Architecture
+description: Understanding the core architecture and design patterns of the SenangStart CSS framework
+---
+
+# SenangStart CSS Architecture
+
+This skill covers the core architectural concepts of SenangStart CSS - a utility-first CSS framework using natural language naming conventions.
+
+## Core Philosophy: Intent-First CSS
+
+SenangStart CSS replaces abstract utility class names with **Natural Adjectives** that read like human language:
+
+| Framework | Approach |
+|-----------|----------|
+| Tailwind | `class="flex items-center p-4 bg-blue-500"` |
+| SenangStart | `layout="flex items:center" space="p:small" visual="bg:blue-500"` |
+
+## The Tri-Attribute System
+
+All utilities are organized into three semantic HTML attributes:
+
+### 1. `layout` - Structure & Positioning
+Controls how elements are arranged and positioned:
+- Display modes: `flex`, `grid`, `block`, `inline`
+- Flex properties: `row`, `col`, `wrap`, `items:center`, `justify:between`
+- Grid: `cols:3`, `rows:2`, `gap:medium`
+- Positioning: `relative`, `absolute`, `fixed`, `sticky`
+
+### 2. `space` - Spacing & Dimensions
+Controls size and spacing:
+- Padding: `p:small`, `p-x:medium`, `p-t:big`
+- Margin: `m:auto`, `m-b:giant`, `m-x:vast`
+- Width/Height: `w:full`, `h:screen`, `min-w:0`, `max-h:fit`
+- Gap: `gap:medium`, `gap-x:small`
+
+### 3. `visual` - Appearance & Effects
+Controls visual presentation:
+- Colors: `bg:primary`, `text:white`, `border-color:grey`
+- Borders: `border:thin`, `rounded:big`
+- Typography: `text-size:giant`, `font:bold`, `line:tight`
+- Effects: `shadow:medium`, `opacity:50`, `blur:small`
+- Transforms: `scale:110`, `rotate:45`, `translate-x:medium`
+
+## Semantic Scale System
+
+Instead of numeric values, SenangStart uses human-readable scales:
+
+### Spacing Scale
+```
+none → thin → regular → thick → tiny → small → medium → big → giant → vast
+0px    1px    2px       3px      4px    8px      16px    32px   48px    64px
+```
+
+Extended multipliers: `small-2x`, `medium-2x`, `big-2x`, etc.
+
+### Other Scales
+- **Radius**: `none`, `small`, `medium`, `big`, `round`
+- **Shadow**: `none`, `small`, `medium`, `big`, `giant`
+- **Font Size**: `tiny`, `small`, `base`, `medium`, `big`, `giant`, `vast`
+
+## Source Code Structure
+
+```
+src/
+├── cdn/
+│   ├── senangstart-engine.js    # Browser JIT runtime (core)
+│   └── tw-conversion-engine.js  # Tailwind converter
+├── cli/
+│   ├── index.js                 # CLI entry point
+│   └── commands/                # init, build, dev commands
+├── compiler/
+│   ├── parser.js                # Attribute parser
+│   ├── tokenizer.js             # Token extraction
+│   └── generators/              # CSS generators
+├── config/
+│   └── defaults.js              # Default configuration
+├── core/
+│   ├── constants.js             # BREAKPOINTS, STATES, etc.
+│   └── tokenizer-core.js        # Shared tokenizer logic
+├── definitions/                 # ⭐ Single Source of Truth
+│   ├── index.js                 # Central export
+│   ├── layout*.js               # Layout utilities
+│   ├── space.js                 # Spacing utilities
+│   └── visual*.js               # Visual utilities
+└── utils/
+    └── css-utils.js             # CSS helper functions
+```
+
+## Definitions: Single Source of Truth
+
+All utility definitions live in `src/definitions/`. Each definition object contains:
+
+```javascript
+{
+  name: 'display',           // Utility name
+  property: 'display',       // CSS property(s)
+  category: 'layout',        // Category for docs
+  attribute: 'layout',       // HTML attribute
+  description: 'Controls...', // English description
+  descriptionMs: 'Mengawal...', // Malay description
+  syntax: 'flex | grid | block | ...', // Usage syntax
+  values: [                  // Possible values
+    { name: 'flex', value: 'flex', description: '...' }
+  ],
+  examples: [                // Code examples
+    { code: 'layout="flex"', description: '...' }
+  ]
+}
+```
+
+Definitions drive:
+- JIT engine behavior
+- Documentation generation
+- Test expectations
+- Type definitions
+
+## Configuration System
+
+Users can extend/override defaults via `senangstart.config.js`:
+
+```javascript
+export default {
+  theme: {
+    spacing: { /* custom values */ },
+    colors: { /* brand colors */ },
+    // ... other scales
+  },
+  darkMode: 'media',  // 'media' | 'selector'
+  preflight: true     // Include base reset
+}
+```
+
+## Responsive Design
+
+Breakpoint prefixes on any utility:
+```html
+<div layout="flex mob:block tab:flex-row lap:gap:medium">
+```
+
+Breakpoints:
+- `mob`: 480px
+- `tab`: 768px  
+- `lap`: 1024px
+- `desk`: 1280px
+
+## State Variants
+
+State prefixes for interactive styling:
+```html
+<div visual="bg:white hover:bg:light focus:ring:thin active:scale:95">
+```
+
+Supported states: `hover`, `focus`, `active`, `focus-visible`, `disabled`, `group-hover`
+
+## Dark Mode
+
+Automatic dark mode support:
+```html
+<div visual="bg:white dark:bg:dark text:black dark:text:white">
+```
+
+Configured via `darkMode: 'media'` (system) or `darkMode: 'selector'` (class-based).