@bookklik/senangstart-css 0.2.5 → 0.2.7

package/.agent/skills/tailwind-conversion/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: Tailwind CSS Conversion
+description: Converting Tailwind CSS to SenangStart CSS using the conversion engine
+---
+
+# Tailwind CSS Conversion
+
+This skill covers converting Tailwind CSS classes to SenangStart CSS using the built-in conversion engine.
+
+## Conversion Engine Files
+
+| File | Purpose |
+|------|---------|
+| `src/cdn/tw-conversion-engine.js` | Browser-based converter |
+| `scripts/convert-tailwind.js` | CLI conversion script |
+| `dist/senangstart-tw.min.js` | CDN-ready converter bundle |
+
+## CLI Usage
+
+### Convert HTML File
+```bash
+node scripts/convert-tailwind.js input.html -o output.html
+```
+
+### Convert Inline String
+```bash
+node scripts/convert-tailwind.js --string "<div class='flex p-4 bg-blue-500'>"
+```
+
+### Exact Mode (Preserve Numeric Values)
+```bash
+node scripts/convert-tailwind.js --exact input.html -o output.html
+```
+
+## Conversion Modes
+
+### Semantic Mode (Default)
+
+Maps Tailwind numeric scales to SenangStart semantic names:
+
+| Tailwind | SenangStart |
+|----------|-------------|
+| `p-0` | `p:none` |
+| `p-1` | `p:thin` |
+| `p-2` | `p:regular` |
+| `p-4` | `p:small` |
+| `p-8` | `p:big` |
+| `rounded-sm` | `rounded:small` |
+| `rounded-lg` | `rounded:medium` |
+| `text-sm` | `text-size:small` |
+| `text-2xl` | `text-size:giant` |
+
+### Exact Mode (`--exact` or `tw-` prefix)
+
+Preserves Tailwind's original values with `tw-` prefix:
+
+| Tailwind | SenangStart (Exact) |
+|----------|---------------------|
+| `p-4` | `p:tw-4` |
+| `rounded-lg` | `rounded:tw-lg` |
+| `text-2xl` | `text-size:tw-2xl` |
+
+The JIT engine includes CSS variables for all Tailwind values:
+```css
+:root {
+  --tw-4: 1rem;
+  --tw-lg: 0.5rem;
+  --tw-2xl: 1.5rem;
+  /* ... */
+}
+```
+
+## Scale Mappings
+
+### Spacing Scale (`spacingScale`)
+
+```javascript
+const spacingScale = {
+  '0': 'none',
+  'px': 'thin',
+  '0.5': 'thin',
+  '1': 'regular',
+  '1.5': 'thick',
+  '2': 'tiny',
+  '3': 'tiny-2x',
+  '4': 'small',
+  '5': 'small-2x',
+  '6': 'small-3x',
+  '8': 'medium',
+  '10': 'medium-2x',
+  '12': 'big',
+  '16': 'giant',
+  '20': 'giant-2x',
+  '24': 'vast',
+  // ... extended scale
+};
+```
+
+### Radius Scale (`radiusScale`)
+
+```javascript
+const radiusScale = {
+  'none': 'none',
+  'sm': 'small',
+  '': 'small',      // default rounded
+  'md': 'small',
+  'lg': 'medium',
+  'xl': 'medium',
+  '2xl': 'big',
+  '3xl': 'big',
+  'full': 'round'
+};
+```
+
+### Shadow Scale (`shadowScale`)
+
+```javascript
+const shadowScale = {
+  'sm': 'small',
+  '': 'small',      // default shadow
+  'md': 'medium',
+  'lg': 'medium',
+  'xl': 'big',
+  '2xl': 'giant',
+  'none': 'none'
+};
+```
+
+### Font Size Scale (`fontSizeScale`)
+
+```javascript
+const fontSizeScale = {
+  'xs': 'tiny',
+  'sm': 'small',
+  'base': 'base',
+  'lg': 'medium',
+  'xl': 'big',
+  '2xl': 'giant',
+  '3xl': 'vast',
+  // ...
+};
+```
+
+## Class Transformation Examples
+
+### Layout Classes
+```
+flex          → layout="flex"
+grid          → layout="grid"
+items-center  → layout="items:center"
+justify-between → layout="justify:between"
+hidden        → layout="hidden"
+```
+
+### Spacing Classes
+```
+p-4           → space="p:small"
+px-6          → space="p-x:small-3x"
+mt-8          → space="m-t:medium"
+gap-4         → space="gap:small"
+w-full        → space="w:full"
+h-screen      → space="h:screen"
+```
+
+### Visual Classes
+```
+bg-blue-500   → visual="bg:blue-500"
+text-white    → visual="text:white"
+rounded-lg    → visual="rounded:medium"
+shadow-md     → visual="shadow:medium"
+opacity-50    → visual="opacity:50"
+```
+
+### State Variants
+```
+hover:bg-blue-600  → visual="hover:bg:blue-600"
+focus:ring-2       → visual="focus:ring:regular"
+active:scale-95    → visual="active:scale:95"
+```
+
+### Responsive Prefixes
+```
+md:flex       → layout="tab:flex"
+lg:grid-cols-3 → layout="lap:cols:3"
+xl:p-8        → space="desk:p:medium"
+```
+
+Breakpoint mapping:
+| Tailwind | SenangStart |
+|----------|-------------|
+| `sm` | `mob` |
+| `md` | `tab` |
+| `lg` | `lap` |
+| `xl` | `desk` |
+
+## CDN Converter Usage
+
+Load converter in browser:
+```html
+<script src="https://unpkg.com/@bookklik/senangstart-css/dist/senangstart-tw.min.js"></script>
+<script>
+  // Convert Tailwind classes
+  const result = SenangStartTW.convert('flex items-center p-4 bg-blue-500');
+  console.log(result);
+  // Output: { layout: 'flex items:center', space: 'p:small', visual: 'bg:blue-500' }
+</script>
+```
+
+## Modifying Conversion Logic
+
+### Adding New Mappings
+
+In `src/cdn/tw-conversion-engine.js`:
+
+```javascript
+// Add to appropriate handler
+function convertVisualClass(cls) {
+  // ADD: New class pattern
+  if (cls.startsWith('my-prefix-')) {
+    const value = cls.replace('my-prefix-', '');
+    return `my-utility:${myScale[value] || value}`;
+  }
+  // ... existing handlers
+}
+```
+
+### Testing Conversions
+
+```bash
+npm run test:unit  # Includes convert-tailwind.test.js
+```
+
+Test file: `tests/unit/convert-tailwind.test.js`
+
+## Common Conversion Challenges
+
+### Arbitrary Values
+Tailwind's arbitrary values `[...]` are preserved:
+```
+text-[#ff0000]  → visual="text:[#ff0000]"
+w-[200px]       → space="w:[200px]"
+```
+
+### Compound Classes
+Some Tailwind classes map to multiple SenangStart properties:
+```
+divide-y        → visual="divide-y:thin"
+ring-2          → visual="ring:regular"
+```
+
+### Unsupported Classes
+Classes without direct mapping are flagged:
+```
+// In conversion output
+/* UNMAPPED: prose lg:prose-xl */
+```
+
+## Best Practices
+
+1. **Run in semantic mode first** - Natural names are more maintainable
+2. **Use exact mode for gradual migration** - When you need pixel-perfect output
+3. **Check unmapped classes** - Some Tailwind plugins need manual conversion
+4. **Verify output** - Always test converted HTML in browser
+5. **Update scales if needed** - Extend SenangStart scales for custom Tailwind values

package/.agent/workflows/add-utility.md

@@ -0,0 +1,155 @@
+---
+description: Add new CSS utilities to the framework with definitions, engine, docs, and tests
+---
+
+# Add New Utility Workflow
+
+## Overview
+
+Adding a new utility requires updates to 4 areas:
+1. **Definition** - Single source of truth in `src/definitions/`
+2. **JIT Engine** - Runtime handler in `src/cdn/senangstart-engine.js`
+3. **Documentation** - Auto-generated via `npm run docs:generate`
+4. **Tests** - Unit tests in `tests/unit/`
+
+## Step 1: Create/Update Definition
+
+1. Identify the appropriate definition file:
+   - `layout-*.js` - Layout utilities
+   - `space.js` - Spacing utilities
+   - `visual-*.js` - Visual utilities
+
+2. Add the definition object:
+```javascript
+export const myUtility = {
+  name: 'my-utility',
+  property: 'my-css-property',
+  category: 'visual',  // layout | space | visual
+  attribute: 'visual', // Which HTML attribute
+  description: 'Does something useful',
+  descriptionMs: 'Melakukan sesuatu yang berguna',
+  syntax: 'my-utility:<value>',
+  values: [
+    { name: 'option1', value: 'css-value-1', description: 'Option 1' },
+    { name: 'option2', value: 'css-value-2', description: 'Option 2' }
+  ],
+  examples: [
+    { code: 'visual="my-utility:option1"', description: 'Example usage' }
+  ],
+  notes: 'Additional notes for documentation'
+};
+```
+
+3. Export in the definition file and `src/definitions/index.js`
+
+## Step 2: Implement in JIT Engine
+
+Edit `src/cdn/senangstart-engine.js`:
+
+1. Find the appropriate handler section (layout/space/visual)
+2. Add the utility pattern matching:
+
+```javascript
+// In generateVisualRule or similar function
+if (prop === 'my-utility') {
+  if (value === 'option1') return 'my-css-property: css-value-1';
+  if (value === 'option2') return 'my-css-property: css-value-2';
+  // Or with scales:
+  const scaleValue = config.theme.myScale?.[value];
+  if (scaleValue) return `my-css-property: ${scaleValue}`;
+}
+```
+
+3. If using a new scale, add to `defaultConfig.theme`:
+```javascript
+myScale: {
+  'small': '4px',
+  'medium': '8px',
+  'big': '16px'
+}
+```
+
+## Step 3: Generate Documentation
+
+// turbo
+1. Auto-generate reference docs:
+```bash
+npm run docs:generate
+```
+
+2. Verify output in:
+   - `docs/reference/<category>/<utility-name>.md`
+   - `docs/ms/reference/<category>/<utility-name>.md`
+
+## Step 4: Write Tests
+
+1. Add to existing test file or create new one in `tests/unit/`:
+
+```javascript
+import { test, describe } from 'node:test';
+import assert from 'node:assert';
+
+describe('my-utility', () => {
+  test('generates correct CSS for option1', () => {
+    const result = generateVisualRule('my-utility', 'option1', config);
+    assert.strictEqual(result, 'my-css-property: css-value-1');
+  });
+});
+```
+
+// turbo
+2. Run tests:
+```bash
+npm test
+```
+
+## Step 5: Rebuild Distribution
+
+// turbo
+1. Rebuild to include changes:
+```bash
+npm run build:dist
+```
+
+## Verification Checklist
+
+- [ ] Definition has all required fields: `name`, `property`, `category`, `attribute`, `description`, `descriptionMs`, `syntax`, `values`, `examples`
+- [ ] JIT engine handles all defined values
+- [ ] Documentation generates correctly for EN and MS
+- [ ] Tests pass
+- [ ] Distribution builds successfully
+
+## Definition Required Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Utility name (e.g., 'display', 'bg') |
+| `property` | string/array | CSS property(s) affected |
+| `category` | string | 'layout', 'space', or 'visual' |
+| `attribute` | string | HTML attribute this belongs to |
+| `description` | string | English description |
+| `descriptionMs` | string | Malay description |
+| `syntax` | string | Usage syntax pattern |
+| `values` | array | Possible values with descriptions |
+| `examples` | array | Usage examples |
+| `notes` | string | (Optional) Extra documentation notes |
+
+## Common Patterns
+
+**Boolean/Toggle Utility:**
+```javascript
+values: [{ name: 'true', value: 'inherit', description: 'Enable' }]
+```
+
+**Scale-Based Utility:**
+```javascript
+values: Object.keys(theme.myScale).map(k => ({ name: k, ... }))
+```
+
+**Arbitrary Value Support:**
+```javascript
+// In JIT: Allow [value] pattern
+if (value.startsWith('[') && value.endsWith(']')) {
+  return `my-property: ${value.slice(1, -1)}`;
+}
+```

package/.agent/workflows/build.md

@@ -0,0 +1,97 @@
+---
+description: Build distribution files and publish to npm
+---
+
+# Build & Release Workflow
+
+## Build Distribution Files
+
+// turbo
+1. Bundle JIT engine and TW converter:
+```bash
+npm run build:dist
+```
+
+This creates in `dist/`:
+- `senangstart-css.js` - Unminified JIT engine
+- `senangstart-css.min.js` - Minified JIT engine (~42KB)
+- `senangstart-tw.js` - Unminified TW converter
+- `senangstart-tw.min.js` - Minified TW converter
+
+Also copies to `docs/public/assets/` for VitePress.
+
+## Full Production Build
+
+1. Build everything (dist + docs):
+```bash
+npm run build
+```
+
+Sequence:
+1. `build:dist` - Bundle JS files
+2. `docs:generate` - Generate reference docs
+3. `vitepress build docs` - Build static site
+4. `docs:llms` - Generate LLM context file
+
+## Pre-publish Verification
+
+// turbo
+1. Run all tests before publishing:
+```bash
+npm test
+```
+
+2. Verify build succeeds:
+```bash
+npm run build:dist
+```
+
+3. Check package.json version is updated
+
+## Publish to npm
+
+1. Login to npm (if not already):
+```bash
+npm login
+```
+
+2. Publish the package:
+```bash
+npm publish
+```
+
+Note: `prepublishOnly` script auto-runs `build:dist` before publish.
+
+## GitHub Pages Deployment
+
+Deployment is automated via GitHub Actions (`.github/workflows/deploy-docs.yml`):
+
+**Trigger**: Push to `master` branch or manual dispatch
+
+**Steps**:
+1. Checkout code
+2. Setup Node.js 20
+3. Install dependencies (`npm ci`)
+4. Generate docs (`npm run docs:generate`)
+5. Build with VitePress (`npm run build`)
+6. Run tests (`npm test`)
+7. Deploy to GitHub Pages
+
+## Build Outputs
+
+| File | Purpose | Size |
+|------|---------|------|
+| `dist/senangstart-css.min.js` | CDN distribution | ~42KB |
+| `dist/senangstart-tw.min.js` | TW converter CDN | ~10KB |
+| `docs/.vitepress/dist/` | Static docs site | - |
+
+## Version Bumping
+
+Before release, update version in:
+1. `package.json` - Main version field
+2. `scripts/build-dist.js` - Banner comments (optional)
+
+Semantic versioning:
+- PATCH (0.2.x) - Bug fixes
+- MINOR (0.x.0) - New features, backward compatible
+- MAJOR (x.0.0) - Breaking changes

package/.agent/workflows/dev.md

@@ -0,0 +1,58 @@
+---
+description: Start development server with hot reload for docs or CLI watch mode
+---
+
+# Development Workflow
+
+## Start Documentation Dev Server
+
+// turbo
+1. Start VitePress dev server:
+```bash
+npm run docs:dev
+```
+
+This launches the documentation site at `http://localhost:5173` with hot reload.
+
+## CLI Watch Mode
+
+// turbo
+1. Run the CLI in development watch mode:
+```bash
+npm run dev
+```
+
+Or using the CLI directly:
+```bash
+senangstart dev
+```
+
+Options:
+- `--no-preflight` - Exclude Preflight base styles
+- `--config <path>` - Custom config file path (default: `senangstart.config.js`)
+
+## Initialize New Project
+
+1. Create a new config file:
+```bash
+senangstart init
+```
+
+This generates `senangstart.config.js` in the current directory.
+
+## Testing Changes
+
+After making changes to source files:
+1. The docs dev server will auto-reload for `docs/` changes
+2. For `src/` changes affecting JIT, rebuild with `npm run build:dist`
+3. Run tests to verify: `npm test`
+
+## Key Development Files
+
+| Purpose | Location |
+|---------|----------|
+| JIT Engine | `src/cdn/senangstart-engine.js` |
+| Definitions | `src/definitions/*.js` |
+| CLI Commands | `src/cli/commands/*.js` |
+| Compiler | `src/compiler/` |
+| Config | `src/config/defaults.js` |

package/.agent/workflows/docs.md

@@ -0,0 +1,113 @@
+---
+description: Generate, build, and manage documentation from definitions
+---
+
+// turbo-all
+
+# Documentation Workflow
+
+## Generate Docs from Definitions
+
+// turbo
+1. Auto-generate reference documentation from utility definitions:
+```bash
+npm run docs:generate
+```
+
+This reads `src/definitions/*.js` and generates markdown files in:
+- `docs/reference/` (English)
+- `docs/ms/reference/` (Malay)
+
+Options:
+- `--locale en|ms` - Generate for specific locale
+- `--dry-run` - Preview without writing files
+
+## Check Doc Sync Status
+
+// turbo
+1. Compare generated docs with definitions:
+```bash
+npm run docs:sync-check
+```
+
+## Extract Syntax Reference
+
+// turbo
+1. Generate syntax reference files:
+```bash
+npm run docs:syntax
+```
+
+Outputs:
+- `docs/SYNTAX-REFERENCE.md`
+- `docs/syntax-reference.json`
+
+## Generate LLM Context File
+
+// turbo
+1. Build llms.txt for AI context:
+```bash
+npm run docs:llms
+```
+
+Creates `docs/public/llms.txt` with utility definitions.
+
+## Build Production Docs
+
+1. Full production build (includes dist + docs):
+```bash
+npm run build
+```
+
+This runs:
+1. `npm run build:dist` - Build distribution files
+2. `npm run docs:generate` - Generate reference docs
+3. `vitepress build docs` - Build VitePress site
+4. `npm run docs:llms` - Generate LLM file
+
+## Documentation Structure
+
+```
+docs/
+├── .vitepress/         # VitePress config
+├── examples/           # Code examples
+├── guide/              # User guide pages
+│   ├── getting-started.md
+│   ├── philosophy.md
+│   ├── tri-attribute.md
+│   └── ...
+├── ms/                 # Malay translations
+│   └── reference/      # Auto-generated Malay docs
+├── public/             # Static assets
+│   ├── assets/         # Bundled JS files
+│   └── llms.txt        # LLM context
+└── reference/          # Auto-generated English docs
+    ├── layout/
+    ├── space/
+    └── visual/
+```
+
+## Adding New Documentation
+
+### Manual Guide Pages
+1. Create/edit markdown files in `docs/guide/`
+2. Update `docs/.vitepress/config.js` sidebar if needed
+
+### Auto-Generated Reference Pages
+1. Add/update definitions in `src/definitions/*.js`
+2. Run `npm run docs:generate`
+3. Verify with `npm run docs:sync-check`
+
+## Localization
+
+Definitions include both English and Malay descriptions:
+```javascript
+{
+  name: 'display',
+  description: 'Controls element display type',
+  descriptionMs: 'Mengawal jenis paparan elemen',
+  // ...
+}
+```
+
+The generator automatically uses the appropriate description for each locale.