npm - @bookklik/senangstart-css - Versions diffs - 0.1.2 → 0.1.4 - Mend

@bookklik/senangstart-css 0.1.2 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (200) hide show

package/docs/ms/examples/index.md ADDED Viewed

@@ -0,0 +1,87 @@
+# Contoh
+Contoh komponen sedia guna dibina dengan SenangStart CSS.
+## Pautan Pantas
+- [Kad](/ms/examples/cards) — Kad profil, kad harga, kad ciri
+- [Navigasi](/ms/examples/navigation) — Navbar, sidebar, menu
+- [Bahagian Hero](/ms/examples/hero) — Hero halaman pendaratan
+- [Borang](/ms/examples/forms) — Input, butang, layout borang
+## Bermula
+Semua contoh menggunakan CDN SenangStart untuk penggunaan tanpa konfigurasi:
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <script src="https://unpkg.com/@bookklik/senangstart-css/dist/senangstart-css.min.js"></script>
+</head>
+<body>
+  <!-- Tampal mana-mana contoh di sini -->
+</body>
+</html>
+```
+## Kad Ringkas
+```html
+<div
+  layout="flex col"
+  space="w:[320px] p:medium"
+  visual="bg:white rounded:big shadow:medium"
+>
+  <h3 visual="font:bold text-size:big text:dark">Tajuk Kad</h3>
+  <p space="m-t:small" visual="text:grey">
+    Penerangan kad di sini.
+  </p>
+  <button
+    space="m-t:medium p-y:small"
+    visual="bg:primary text:white rounded:medium"
+  >
+    Tindakan
+  </button>
+</div>
+```
+## Navigasi Asas
+```html
+<nav
+  layout="flex between center"
+  space="p-x:big p-y:small"
+  visual="bg:white shadow:small"
+>
+  <div visual="font:bold text-size:big text:primary">Logo</div>
+  <div layout="flex" space="g:medium">
+    <a visual="text:dark hover:text:primary">Laman Utama</a>
+    <a visual="text:grey hover:text:primary">Tentang</a>
+    <a visual="text:grey hover:text:primary">Hubungi</a>
+  </div>
+</nav>
+```
+## Bahagian Hero
+```html
+<section
+  layout="flex col center"
+  space="p:giant min-h:[80vh]"
+  visual="bg:dark text:white"
+>
+  <h1 visual="text-size:vast font:bold text:center">
+    Selamat Datang
+  </h1>
+  <p space="m-t:medium max-w:[600px]" visual="text:light text:center text-size:big">
+    Bina antara muka cantik dengan bahasa semula jadi.
+  </p>
+  <button
+    space="m-t:big p-x:big p-y:small"
+    visual="bg:primary text:white rounded:medium hover:bg:[#2563EB]"
+  >
+    Bermula
+  </button>
+</section>
+```

package/docs/ms/examples/navigation.md ADDED Viewed

@@ -0,0 +1,144 @@
+# Contoh Navigasi
+Corak navigasi dibina dengan SenangStart CSS.
+## Navbar Ringkas
+```html
+<nav
+  layout="flex between center"
+  space="p-x:big p-y:small"
+  visual="bg:white shadow:small"
+>
+  <div visual="font:bold text-size:big text:primary">Logo</div>
+  <div layout="flex" space="g:medium">
+    <a visual="text:dark hover:text:primary">Laman Utama</a>
+    <a visual="text:grey hover:text:primary">Tentang</a>
+    <a visual="text:grey hover:text:primary">Hubungi</a>
+  </div>
+</nav>
+```
+## Navigasi Fixed
+```html
+<nav
+  layout="flex between center fixed z:top"
+  space="w:[100%] p-x:big p-y:small"
+  visual="bg:white shadow:small"
+>
+  <div visual="font:bold text-size:big text:primary">Logo</div>
+  <div layout="flex" space="g:medium">
+    <a visual="text:dark hover:text:primary font:medium">Laman Utama</a>
+    <a visual="text:grey hover:text:primary">Produk</a>
+    <a visual="text:grey hover:text:primary">Harga</a>
+    <a visual="text:grey hover:text:primary">Tentang</a>
+  </div>
+  <button
+    space="p-x:medium p-y:tiny"
+    visual="bg:primary text:white rounded:medium hover:bg:[#2563EB]"
+  >
+    Daftar
+  </button>
+</nav>
+```
+## Navigasi Responsif
+```html
+<!-- Butang menu mudah alih (tersembunyi pada tablet+) -->
+<button layout="block tab:hidden" visual="text:dark">
+  ☰ Menu
+</button>
+<!-- Navigasi desktop (tersembunyi pada mudah alih) -->
+<nav
+  layout="hidden tab:flex between center"
+  space="p-x:big p-y:small"
+  visual="bg:white"
+>
+  <div visual="font:bold text-size:big">Logo</div>
+  <div layout="flex" space="g:medium">
+    <a visual="text:dark hover:text:primary">Laman Utama</a>
+    <a visual="text:grey hover:text:primary">Tentang</a>
+  </div>
+</nav>
+```
+## Navigasi Sidebar
+```html
+<aside
+  layout="flex col"
+  space="w:[250px] h:[100vh] p:medium"
+  visual="bg:dark"
+>
+  <div space="m-b:big" visual="font:bold text-size:big text:white">
+    Dashboard
+  </div>
+  <nav layout="flex col" space="g:tiny">
+    <a
+      space="p:small"
+      visual="text:white bg:[rgba(255,255,255,0.1)] rounded:small"
+    >
+      🏠 Laman Utama
+    </a>
+    <a
+      space="p:small"
+      visual="text:light hover:bg:[rgba(255,255,255,0.1)] rounded:small"
+    >
+      📊 Analitik
+    </a>
+    <a
+      space="p:small"
+      visual="text:light hover:bg:[rgba(255,255,255,0.1)] rounded:small"
+    >
+      👥 Pengguna
+    </a>
+    <a
+      space="p:small"
+      visual="text:light hover:bg:[rgba(255,255,255,0.1)] rounded:small"
+    >
+      ⚙️ Tetapan
+    </a>
+  </nav>
+</aside>
+```
+## Breadcrumb
+```html
+<nav layout="flex" space="g:small p:small">
+  <a visual="text:primary hover:text:[#2563EB]">Laman Utama</a>
+  <span visual="text:grey">/</span>
+  <a visual="text:primary hover:text:[#2563EB]">Produk</a>
+  <span visual="text:grey">/</span>
+  <span visual="text:dark">Halaman Semasa</span>
+</nav>
+```
+## Navigasi Tab
+```html
+<div layout="flex" space="g:none" visual="border-b:light">
+  <button
+    space="p-x:medium p-y:small"
+    visual="text:primary border-b:[2px] border:primary"
+  >
+    Tab 1
+  </button>
+  <button
+    space="p-x:medium p-y:small"
+    visual="text:grey hover:text:dark"
+  >
+    Tab 2
+  </button>
+  <button
+    space="p-x:medium p-y:small"
+    visual="text:grey hover:text:dark"
+  >
+    Tab 3
+  </button>
+</div>
+```

package/docs/ms/guide/cdn.md ADDED Viewed

@@ -0,0 +1,110 @@
+# CDN (Tanpa Bina)
+Cara terpantas untuk guna SenangStart CSS — tiada langkah bina diperlukan.
+## Mula Pantas
+Tambah satu tag skrip ke HTML anda:
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Aplikasi Saya</title>
+  <script src="https://unpkg.com/@bookklik/senangstart-css/dist/senangstart-css.min.js"></script>
+</head>
+<body>
+  <div
+    layout="flex col center"
+    space="p:big"
+    visual="bg:primary text:white rounded:big"
+  >
+    Hello SenangStart!
+  </div>
+</body>
+</html>
+```
+Itu sahaja! Tiada npm, tiada proses bina, tiada konfigurasi.
+## Bagaimana Ia Berfungsi
+CDN JIT (Just-In-Time) runtime:
+1. **Imbas DOM** — Cari semua elemen dengan atribusi `layout`, `space`, dan `visual`
+2. **Jana CSS** — Kompil style secara on-the-fly dalam pelayar
+3. **Suntik Styles** — Cipta tag `<style>` dengan CSS terkompil
+4. **Pantau Perubahan** — Guna MutationObserver untuk kandungan dinamik
+## Konfigurasi Tersuai
+Tindih ganti nilai tema lalai dengan config inline:
+```html
+<script type="senangstart/config">
+{
+  "theme": {
+    "colors": {
+      "brand": "#8B5CF6",
+      "accent": "#EC4899"
+    },
+    "spacing": {
+      "huge": "256px"
+    }
+  }
+}
+</script>
+<script src="https://unpkg.com/@bookklik/senangstart-css/dist/senangstart-css.min.js"></script>
+```
+Sekarang anda boleh guna nilai tersuai anda:
+```html
+<div visual="bg:brand text:accent">Warna tersuai!</div>
+<div space="p:huge">Padding huge!</div>
+```
+## Pembangunan Tempatan
+Untuk pembangunan tempatan tanpa CDN, guna fail JIT tempatan:
+```html
+<script src="./path/to/senangstart/src/cdn/jit.js"></script>
+```
+## Pertimbangan Prestasi
+::: warning Bila Guna CLI
+CDN JIT sesuai untuk:
+- Prototaip dan eksperimen
+- Mempelajari rangka kerja
+- Projek kecil dan demo
+- Pembangunan pantas
+Untuk aplikasi produksi, pertimbangkan [CLI build](/ms/guide/cli) untuk:
+- Prestasi lebih baik (CSS pra-kompil)
+- Saiz fail lebih kecil
+- Tiada beban kelola
+:::
+## Sokongan Pelayar
+CDN JIT menggunakan ciri JavaScript moden:
+- Sintaksis ES6+
+- API MutationObserver
+- CSS Custom Sari Diri
+Disokong dalam semua pelayar moden (Chrome, Firefox, Safari, Edge).
+## Debugging
+Buka Developer Tools pelayar anda untuk lihat:
+```
+[SenangStart CSS] JIT runtime initialized ✓
+```
+Jika anda tidak nampak mesej ini, periksa bahawa:
+1. Skrip memuatkan dengan betul
+2. Tiada ralat JavaScript dalam konsol
+3. Config JSON (jika digunakan) adalah sah

package/docs/ms/guide/cli.md ADDED Viewed

@@ -0,0 +1,174 @@
+# Bina CLI
+Guna CLI untuk bina sedia produksi dengan output teroptimum.
+## Pemasangan
+```bash
+# Pasang secara global
+npm install -g @bookklik/senangstart-css
+# Atau guna npx (tanpa pasang)
+npx @bookklik/senangstart-css init
+```
+## Arahan
+### `senangstart init`
+Cipta fail konfigurasi:
+```bash
+senangstart init
+```
+Ini mencipta `senangstart.config.js` dalam root projek anda dengan lalai yang baik.
+### `senangstart build`
+Kompil CSS dari fail sumber anda:
+```bash
+senangstart build
+```
+**Pilihan:**
+| Pilihan | Penerangan |
+|---------|------------|
+| `--minify` | Minify output CSS |
+| `--config <path>` | Laluan ke fail config |
+```bash
+# Build produksi dengan minification
+senangstart build --minify
+# Guna config tersuai
+senangstart build --config ./custom.config.js
+```
+### `senangstart dev`
+Mod watch untuk pembangunan:
+```bash
+senangstart dev
+```
+Ini memantau fail sumber anda dan membina semula secara automatik apabila ada perubahan.
+## Fail Output
+CLI menghasilkan tiga fail:
+| Fail | Penerangan |
+|------|------------|
+| `public/senangstart.css` | Stylesheet terkompil |
+| `.cursorrules` | Fail konteks AI untuk LLM |
+| `types/senang.d.ts` | Definisi TypeScript |
+## Persediaan Projek
+### 1. Mulakan
+```bash
+cd projek-anda
+npm init -y
+npm i @bookklik/senangstart-css
+npx senangstart init
+```
+### 2. Tambah HTML
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <link rel="stylesheet" href="./public/senangstart.css">
+</head>
+<body>
+  <div
+    layout="flex col center"
+    space="p:big"
+    visual="bg:primary text:white rounded:big"
+  >
+    Hello SenangStart!
+  </div>
+</body>
+</html>
+```
+### 3. Bina
+```bash
+npx senangstart build
+```
+### 4. Pembangunan
+```bash
+npx senangstart dev
+```
+## Skrip Package.json
+Tambah skrip ini ke `package.json` anda:
+```json
+{
+  "scripts": {
+    "build:css": "senangstart build --minify",
+    "dev:css": "senangstart dev"
+  }
+}
+```
+## Integrasi dengan Framework
+### Vite / React / Vue
+Tambah ke proses bina anda:
+```json
+{
+  "scripts": {
+    "dev": "concurrently \"vite\" \"senangstart dev\"",
+    "build": "senangstart build --minify && vite build"
+  }
+}
+```
+### Next.js
+Import CSS yang dijana dalam `_app.js`:
+```jsx
+import '../public/senangstart.css'
+function MyApp({ Component, pageProps }) {
+  return <Component {...pageProps} />
+}
+export default MyApp
+```
+## Integrasi CI/CD
+Tambah ke pipeline bina anda:
+```yaml
+# Contoh GitHub Actions
+- name: Build CSS
+  run: npx senangstart build --minify
+```
+## Perbandingan CDN vs CLI
+| Ciri | CDN JIT | CLI Build |
+|------|---------|-----------|
+| Persediaan | Tanpa config | Memerlukan npm |
+| Langkah Bina | Tiada | Diperlukan |
+| Prestasi | Overhead runtime | Pra-kompil |
+| Saiz Fail | ~15KB JS | Hanya CSS yang digunakan |
+| Kes Penggunaan | Prototaip | Produksi |
+| Kandungan Dinamik | ✅ Automatik | Perlu rebuild |

package/docs/ms/guide/configuration.md ADDED Viewed

@@ -0,0 +1,152 @@
+# Konfigurasi
+Sesuaikan SenangStart CSS dengan `senangstart.config.js`.
+## Mencipta Fail Config
+Jalankan arahan init untuk mencipta fail config:
+```bash
+senangstart init
+```
+Atau cipta secara manual:
+```javascript
+// senangstart.config.js
+export default {
+  // Fail untuk diimbas untuk atribusi SenangStart
+  content: [
+    './**/*.html',
+    './src/**/*.{html,jsx,tsx,vue,svelte}',
+    './components/**/*.{html,jsx,tsx}'
+  ],
+  // Konfigurasi output
+  output: {
+    css: './public/senangstart.css',
+    minify: true,
+    aiContext: './.cursorrules',
+    typescript: './types/senang.d.ts'
+  },
+  // Penyesuaian tema
+  theme: {
+    // Tindih ganti anda di sini
+  }
+}
+```
+## Corak Kandungan
+Tentukan fail mana untuk diimbas:
+```javascript
+content: [
+  './**/*.html',           // Semua fail HTML
+  './src/**/*.jsx',        // Komponen React
+  './pages/**/*.vue',      // Halaman Vue
+  './components/**/*.svelte'
+]
+```
+## Pilihan Output
+| Pilihan | Penerangan | Lalai |
+|---------|------------|-------|
+| `css` | Laluan output CSS | `./public/senangstart.css` |
+| `minify` | Minify output | `false` |
+| `aiContext` | Laluan fail konteks AI | `./.cursorrules` |
+| `typescript` | Laluan definisi TypeScript | `./types/senang.d.ts` |
+## Penyesuaian Tema
+### Spacing Tersuai
+```javascript
+theme: {
+  spacing: {
+    'tiny': '2px',       // Tindih ganti sedia ada
+    'huge': '256px',     // Tambah skala baru
+    'massive': '512px'
+  }
+}
+```
+### Warna Tersuai
+```javascript
+theme: {
+  colors: {
+    'brand': '#8B5CF6',
+    'accent': '#EC4899',
+    'custom': '#FF5733'
+  }
+}
+```
+### Titik Henti Tersuai
+```javascript
+theme: {
+  screens: {
+    'mob': '480px',
+    'tab': '768px',
+    'lap': '1024px',
+    'desk': '1280px',
+    'wide': '1536px'    // Tambah breakpoint lebih lebar
+  }
+}
+```
+### Bayang Tersuai
+```javascript
+theme: {
+  shadow: {
+    'glow': '0 0 20px rgba(59, 130, 246, 0.5)',
+    'inset': 'inset 0 2px 4px rgba(0,0,0,0.1)'
+  }
+}
+```
+## Contoh Penuh
+```javascript
+export default {
+  content: [
+    './src/**/*.{html,jsx,tsx}',
+    './components/**/*.vue'
+  ],
+  output: {
+    css: './dist/styles.css',
+    minify: true,
+    aiContext: './.cursorrules',
+    typescript: './src/types/senang.d.ts'
+  },
+  theme: {
+    spacing: {
+      'huge': '256px'
+    },
+    colors: {
+      'brand': '#8B5CF6',
+      'accent': '#EC4899'
+    },
+    screens: {
+      'wide': '1536px'
+    }
+  }
+}
+```
+## Menggunakan Nilai Tersuai
+Selepas mengkonfigurasi, guna skala tersuai anda:
+```html
+<div space="p:huge">Padding huge tersuai</div>
+<div visual="bg:brand text:accent">Warna tersuai</div>
+<div space="tab:p:big wide:p:huge">Titik Henti tersuai</div>
+```