roda-kabk 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f5508b1dac33bf7629b9c147a7f1798a67e78280862aaacc77fa6114944df277
+  data.tar.gz: 459908e88eb476e96592aa97f8832c53c5bbcd01b446ace3e977b6aca14c1bea
+SHA512:
+  metadata.gz: e3be59177e76c02daad67d4d00c1c6b6c6effd42ad0acee508e1b75b85516760552f0e1839c47e9d9eccc4bec16c6f2f171619f14c533b5dfc4afa001f1302dc
+  data.tar.gz: 1f322e901a43c63bb5ceaec3ebb6314bed76c3384a951e144b79ddf68c7b6b13c189768f03f57d516da856d3bc9680f7a56923dc9e62b248264b6bc617d7d587

data/Gemfile

@@ -0,0 +1,10 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem "sqlite3"
+gem "rackup"
+gem "rspec"
+gem "rack-test"
+gem "logger"
+gem "puma"

data/Gemfile.lock

@@ -0,0 +1,79 @@
+PATH
+  remote: .
+  specs:
+    roda-kabk (0.2.0)
+      kabk (~> 0.2.0)
+      roda (~> 3.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    bigdecimal (4.1.2)
+    concurrent-ruby (1.3.8)
+    diff-lcs (1.6.2)
+    kabk (0.2.0)
+      concurrent-ruby (~> 1.1)
+      sequel (~> 5.0)
+    logger (1.7.0)
+    nio4r (2.7.5)
+    puma (8.0.2)
+      nio4r (~> 2.0)
+    rack (3.2.6)
+    rack-test (2.2.0)
+      rack (>= 1.3)
+    rackup (2.3.1)
+      rack (>= 3)
+    roda (3.106.0)
+      rack
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    sequel (5.107.0)
+      bigdecimal
+    sqlite3 (2.9.5-x64-mingw-ucrt)
+
+PLATFORMS
+  x64-mingw-ucrt
+
+DEPENDENCIES
+  logger
+  puma
+  rack-test
+  rackup
+  roda-kabk!
+  rspec
+  sqlite3
+
+CHECKSUMS
+  bigdecimal (4.1.2) sha256=53d217666027eab4280346fba98e7d5b66baaae1b9c3c1c0ffe89d48188a3fbd
+  concurrent-ruby (1.3.8) sha256=b2f1be836e968ccc78ccfce277ea79c72a88633f22306782c16ff23fb415d1e1
+  diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
+  kabk (0.2.0) sha256=96b8cbea6b28d8ef0e5b9b4d935851833a617d87f14c7b0c39bc50142bf78118
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  nio4r (2.7.5) sha256=6c90168e48fb5f8e768419c93abb94ba2b892a1d0602cb06eef16d8b7df1dca1
+  puma (8.0.2) sha256=c8ed871dfbbe66448ea9ffd46692342d9804d4071522b52b5331b7b6e7b686fb
+  rack (3.2.6) sha256=5ed78e1f73b2e25679bec7d45ee2d4483cc4146eb1be0264fc4d94cb5ef212c2
+  rack-test (2.2.0) sha256=005a36692c306ac0b4a9350355ee080fd09ddef1148a5f8b2ac636c720f5c463
+  rackup (2.3.1) sha256=6c79c26753778e90983761d677a48937ee3192b3ffef6bc963c0950f94688868
+  roda (3.106.0) sha256=1a1cfb13c6690db158a3929e9c9ece88e697fb23b05baae63f07b0773e3bbade
+  roda-kabk (0.2.0)
+  rspec (3.13.2) sha256=206284a08ad798e61f86d7ca3e376718d52c0bc944626b2349266f239f820587
+  rspec-core (3.13.6) sha256=a8823c6411667b60a8bca135364351dda34cd55e44ff94c4be4633b37d828b2d
+  rspec-expectations (3.13.5) sha256=33a4d3a1d95060aea4c94e9f237030a8f9eae5615e9bd85718fe3a09e4b58836
+  rspec-mocks (3.13.8) sha256=086ad3d3d17533f4237643de0b5c42f04b66348c28bf6b9c2d3f4a3b01af1d47
+  rspec-support (3.13.7) sha256=0640e5570872aafefd79867901deeeeb40b0c9875a36b983d85f54fb7381c47c
+  sequel (5.107.0) sha256=019629313205295b007f6df2c5eab19ddc40710d549fd445ac300f2853a370db
+  sqlite3 (2.9.5-x64-mingw-ucrt) sha256=b00d5697994ee8589b6096694a2130aa5567db64373baca55ea98c9bf958f46a
+
+BUNDLED WITH
+  4.0.16

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Parham Taheri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,267 @@
+<h1 align="center">
+  <img src="roda-kabk.svg" alt="Roda Kabk Logo" width="300" />
+  <br>
+  Roda Kabk
+</h1>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/roda-kabk"><img src="https://img.shields.io/gem/v/roda-kabk.svg?color=blue" alt="Gem Version"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+</p>
+
+> **Kabk carries the Ruby to Simorgh**
+
+`roda-kabk` is the official [Roda](https://roda.jeremyevans.net/) plugin for [Kabk](https://github.com/par-taheri/Kabk) — providing a **Smart Dispatch** routing architecture for the Simurgh Panel protocol (v1.6.0). It uses `api_path` defined in `Kabk.register` as the Single Source of Truth for all routes, giving you full control over middleware, authentication, and routing branches.
+
+---
+
+## Features
+
+- **Smart Dispatch Routing (`r.kabk.route`)**: Automatically routes incoming requests to the appropriate `Kabk::RestEngine` resource based on each resource's `api_path`.
+- **Global Static Assets (`r.kabk.statics`)**: Serves pre-built assets (JS, CSS, SVGs, images, fonts, videos) under `/assets/*` and `/simurgh-logo.svg`.
+- **Vue.js SPA Server (`r.kabk.server`)**: Serves the single-page admin dashboard SPA `index.html` with embedded schema injection.
+- **Protocol Schema Manifest (`r.kabk.schema`)**: Exposes dynamic protocol schema JSON.
+- **Pluggable File Uploads (`r.kabk.upload`)**: Seamless integration with **Shrine**, ActiveStorage, or custom storage handlers via configurable procs.
+- **Context Injection**: Pass `context` into `r.kabk.route(context: ...)` to support Kabk's lifecycle hooks and audit fields based on the current user.
+- **Optimistic Concurrency Control (OCC)**: Built-in support for preventing concurrent record overwrite conflicts (`updated_at` / `version`).
+- **Client-Side Data Export**: CSV exports are natively generated on the client-side (frontend) using existing table data and active filters without backend overhead.
+
+---
+
+## Installation
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem 'roda-kabk'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+---
+
+## Quick Start (Smart Dispatch Architecture)
+
+In the new decoupled architecture, `Kabk` no longer manages authentication internally. You handle authentication in Roda and dispatch protected CRUD requests via `r.kabk.route(context: ...)`.
+
+### 1. Setup DB and Sequel Model
+
+Define your user and resource models with `api_path` as the Single Source of Truth:
+
+```ruby
+require 'roda'
+require 'sequel'
+require 'kabk'
+require 'roda/plugins/kabk'
+require 'bcrypt'
+
+DB = Sequel.sqlite
+
+# Authentication Model
+DB.create_table :admin_users do
+  primary_key :id
+  String :username, null: false, unique: true
+  String :password_digest, null: false
+  String :full_name
+  String :avatar_url
+  String :role, default: "admin"
+end
+
+class AdminUser < Sequel::Model
+  plugin :secure_password
+end
+
+DB.create_table :articles do
+  primary_key :id
+  String :title, null: false
+  String :content
+  DateTime :updated_at
+end
+
+class Article < Sequel::Model; end
+
+# Register Entity with Kabk (api_path is the Single Source of Truth)
+Kabk.register(name: "article", table: Article) do
+  title "Articles"
+  plural_name "articles"
+  api_path "/admin/api/articles"
+  concurrency_field "updated_at"
+
+  field :id, type: :number, form_type: :number, primary_key: true
+  field :title, type: :string, form_type: :text, required: true
+  field :content, type: :string, form_type: :textarea
+  field :updated_at, type: :datetime, form_type: :datetime, readonly: true
+end
+```
+
+### 2. Implement Roda Application
+
+Use Roda's routing tree with `r.kabk` helper methods:
+
+```ruby
+class App < Roda
+  plugin :sessions, secret: ENV.fetch("SESSION_SECRET", "super_secret_key_that_is_long_enough_for_session")
+  plugin :json
+  plugin :kabk,
+         system_config: {
+           title: { en: "Admin Dashboard", fa: "پنل مدیریت" },
+           default_locale: "en",
+           supported_locales: ["en", "fa"],
+           direction: "ltr",
+           show_demo_credentials: false,
+           endpoints: {
+             upload: "/admin/api/uploads"
+           },
+           auth: {
+             strategy: "session",
+             sso_redirect_url: nil,
+             login_url: "/admin/api/auth/login",
+             me_url: "/admin/api/auth/me",
+             logout_url: "/admin/api/auth/logout",
+             refresh_url: "/admin/api/auth/refresh",
+             show_demo_credentials: false,
+             login_fields: [
+               { name: "username", label: { en: "Username", fa: "نام کاربری" }, type: "text", required: true },
+               { name: "password", label: { en: "Password", fa: "کلمه عبور" }, type: "password", required: true }
+             ]
+           }
+         },
+         upload_handler: ->(file_param, req) {
+           {
+             url: "/uploads/#{file_param[:filename]}",
+             file_name: file_param[:filename],
+             size: file_param[:tempfile].size,
+             mime_type: file_param[:type]
+           }
+         }
+
+  route do |r|
+    r.kabk.statics
+
+    r.on "admin" do
+      r.is do
+        r.kabk.server
+      end
+
+      r.on "api" do
+        r.get "schema" do
+          r.kabk.schema
+        end
+
+        r.post "uploads" do
+          r.kabk.upload
+        end
+
+        r.on "auth" do
+          r.post "login" do
+            body = JSON.parse(r.body.read) rescue {}
+            user = AdminUser.first(username: body["username"])
+            if user && user.authenticate(body["password"])
+              session[:user_id] = user.id
+              { success: true, data: { id: user.id, username: user.username, role: user.role } }
+            else
+              response.status = 401
+              { success: false, error: { message: "Invalid credentials" } }
+            end
+          end
+
+          r.get "me" do
+            user = AdminUser[session[:user_id]]
+            if user
+              { success: true, data: { id: user.id, username: user.username, role: user.role } }
+            else
+              response.status = 401
+              { success: false, error: { message: "Unauthorized" } }
+            end
+          end
+
+          r.post "logout" do
+            session.clear
+            { success: true, message: "Logged out" }
+          end
+        end
+
+        current_user = AdminUser[session[:user_id]]
+        unless current_user
+          response.status = 401
+          r.halt({ success: false, error: { message: "Unauthorized" } }.to_json)
+        end
+
+        r.kabk.route(context: { current_user: current_user })
+      end
+    end
+  end
+end
+```
+
+---
+
+## Configuration Reference
+
+The `plugin :kabk` method accepts the following options:
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `system_config` | `Hash` / `NilClass` | `nil` | Custom system branding, custom fonts, and localization settings. |
+| `upload_handler` | `Proc` / `Callable` | `nil` | Custom file upload handler block/callable. Processes uploaded file params. |
+
+---
+
+## Request Methods (`r.kabk.*`)
+
+| Method | Description |
+| :--- | :--- |
+| `r.kabk.statics` | Serves static assets (JS, CSS, SVGs, images, fonts, videos) from `/assets/*` and `simurgh-logo.svg`. |
+| `r.kabk.server` | Serves `index.html` (with memoized schema injection) for the Vue.js SPA dashboard. |
+| `r.kabk.schema` | Returns the dynamic protocol schema JSON manifest. |
+| `r.kabk.upload` | Handles multipart file uploads using `upload_handler` or fallback. |
+| `r.kabk.route(context: {})` | Smart Dispatcher: matches the request path against registered `api_path`s and executes CRUD actions (list, get, create, update, delete) on `Kabk::RestEngine`. |
+
+---
+
+## Context Injection & Hooks
+
+By passing `context: { current_user: ... }` to `r.kabk.route`, `Kabk`'s `RestEngine` propagates this context to lifecycle hooks and audit fields. For example, you can write entity hooks in `Kabk` core that verify if a user has permission to delete a record or automatically assign the `created_by` field based on `context[:current_user]`.
+
+---
+
+## File Upload Integration (Shrine Example)
+
+You can connect **Shrine** directly using the `upload_handler` option:
+
+```ruby
+plugin :kabk,
+       upload_handler: ->(file_param, req) {
+         # file_param contains Rack tempfile params: { tempfile: #<File>, filename: "...", type: "..." }
+         uploader = ImageUploader.upload(file_param[:tempfile], :store)
+
+         {
+           url: uploader.url,
+           file_name: file_param[:filename],
+           size: file_param[:tempfile].size,
+           mime_type: file_param[:type]
+         }
+       }
+```
+
+If no `upload_handler` is provided and no file is attached, `r.kabk.upload` returns an `HTTP 422 Unprocessable Entity` error.
+
+---
+
+## Testing
+
+Run the test suite using `rspec`:
+
+```bash
+bundle exec rspec
+```
+
+---
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE).

data/TUTORIAL.md

@@ -0,0 +1,271 @@
+# Roda-Kabk Ultimate Tutorial: Building a Comprehensive Simurgh Admin Panel
+
+Welcome to the **Roda-Kabk Tutorial**. This guide will walk you through building a fully-featured, production-ready admin panel using `roda-kabk` and the Simurgh Panel protocol.
+
+We will translate a complex, real-world schema—including relations, advanced validations, JSON editors, custom fonts, and file uploads—directly into the Ruby Kabk DSL.
+
+---
+
+## 1. Setting Up the Application & System Config
+
+First, we need to mount the plugin in our Roda application and configure the `system_config`. This is where we define custom branding, multilingual support, and custom fonts.
+
+```ruby
+require 'roda'
+require 'sequel'
+require 'kabk'
+require 'roda/plugins/kabk'
+
+class AdminApp < Roda
+  plugin :sessions, secret: ENV.fetch("SESSION_SECRET", "super_secret_key_that_is_long_enough_for_session")
+  plugin :json
+  plugin :kabk,
+         system_config: {
+           title: { en: "Simurgh Panel", fa: "پنل مدیریت سیمرغ" },
+           logo_url: "https://images.unsplash.com/photo-1618005182384-a83a8bd57fbe?w=100&h=100&fit=crop&crop=faces",
+           default_locale: "en",
+           supported_locales: ["en", "fa"],
+           direction: "ltr",
+           show_demo_credentials: false,
+           custom_fonts: [
+             {
+               name: "Inter",
+               url: "https://fonts.gstatic.com/s/inter/v13/UcCO3FwrK3iLTeHuS_fvQtMwCp50KnMw2boKoduKmMEVuLyfAZ9hiA.woff2",
+               format: "woff2",
+               label: { en: "Inter (English)", fa: "اینتر (انگلیسی)" }
+             },
+             {
+               name: "Sahel",
+               url: "https://cdn.jsdelivr.net/gh/rastikerdar/sahel-font@v3.4.0/dist/Sahel.woff2",
+               format: "woff2",
+               label: { en: "Sahel (Persian)", fa: "ساحل (فارسی)" }
+             }
+           ],
+           custom_font_sizes: [
+             { size: "14px", label: { en: "Standard", fa: "عادی" } },
+             { size: "18px", label: { en: "Medium", fa: "متوسط" } },
+             { size: "28px", label: { en: "Large Heading", fa: "تیتر بزرگ" } }
+           ]
+         }
+
+  route do |r|
+    r.kabk.statics
+
+    r.on "admin" do
+      r.is do
+        r.kabk.server
+      end
+
+      r.on "api" do
+        r.get "schema" do
+          r.kabk.schema
+        end
+
+        r.post "uploads" do
+          r.kabk.upload
+        end
+
+        r.on "auth" do
+          r.post "login" do
+            body = JSON.parse(r.body.read) rescue {}
+            user = User.first(email: body["username"] || body["email"])
+            if user && user.authenticate(body["password"])
+              session[:user_id] = user.id
+              { success: true, data: { id: user.id, username: user.email, role: user.role } }
+            else
+              response.status = 401
+              { success: false, error: { message: "Invalid credentials" } }
+            end
+          end
+
+          r.get "me" do
+            user = User[session[:user_id]]
+            if user
+              { success: true, data: { id: user.id, username: user.email, role: user.role } }
+            else
+              response.status = 401
+              { success: false, error: { message: "Unauthorized" } }
+            end
+          end
+
+          r.post "logout" do
+            session.clear
+            { success: true, message: "Logged out" }
+          end
+        end
+
+        current_user = User[session[:user_id]]
+        unless current_user
+          response.status = 401
+          r.halt({ error: "Unauthorized" }.to_json)
+        end
+
+        r.kabk.route(context: { current_user: current_user })
+      end
+    end
+  end
+end
+```
+
+---
+
+## 2. Defining Resources (The DSL)
+
+We will define 5 major resources to showcase different capabilities: `Users`, `Categories`, `Products`, `Support Tickets`, and `News`.
+
+### Resource 1: Users (Badges, Textareas, and Unique Validation)
+
+```ruby
+Kabk.register(name: "users", table: User) do
+  title en: "User Directory", fa: "مدیریت کاربران"
+  icon "Users"
+  api_path "/admin/api/users"
+  group "Access & Users"
+  order 2
+  searchable_fields [:full_name, :email]
+  sortable_fields [:id, :full_name, :role, :birth_date, :created_at]
+  concurrency_field "updated_at"
+
+  field :id, type: :number, form_type: :number, primary_key: true, hidden_in_form: true
+  
+  field :full_name, type: :string, form_type: :text, required: true, validation: { min_length: 3, max_length: 100 }
+  
+  field :email, type: :string, form_type: :text, required: true, validation: {
+    pattern: "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$",
+    unique: true,
+    custom_message: { en: "Email invalid or taken", fa: "فرمت ایمیل معتبر نیست یا قبلاً ثبت شده است" }
+  }
+
+  field :avatar, type: :file, form_type: :image_single, display_as: "thumbnail", nullable: true
+  
+  field :role, type: :string, form_type: :select, display_as: "badge", required: true, default_value: "editor", options: [
+    { label: { en: "Administrator", fa: "مدیر کل" }, value: "admin", color: "purple" },
+    { label: { en: "Editor", fa: "ویرایشگر" }, value: "editor", color: "blue" },
+    { label: { en: "Author", fa: "نویسنده" }, value: "author", color: "emerald" },
+    { label: { en: "Viewer", fa: "مشاهده‌کننده" }, value: "viewer", color: "gray" }
+  ]
+
+  field :bio, type: :string, form_type: :textarea, hidden_in_table: true, accordion: true, rows: 3
+  field :is_active, type: :boolean, form_type: :switch, display_as: "boolean_icon", default_value: true
+  
+  field :birth_date, type: :date, form_type: :date, nullable: true
+  field :created_at, type: :date, form_type: :date, readonly: true, hidden_in_form: true
+end
+```
+
+### Resource 2: Categories (Simple Text and Badges)
+
+```ruby
+Kabk.register(name: "categories", table: Category) do
+  title en: "Categories", fa: "دسته‌بندی‌ها"
+  icon "Tags"
+  api_path "/admin/api/categories"
+  group "Content Management"
+  order 3
+  searchable_fields [:title, :slug]
+  
+  field :id, type: :number, form_type: :number, primary_key: true, hidden_in_form: true
+  field :title, type: :string, form_type: :text, required: true, col_width: 6
+  field :slug, type: :string, form_type: :text, required: true, col_width: 6, validation: { pattern: "^[a-z0-9-]+$" }
+  field :color_code, type: :string, form_type: :text, display_as: "badge", col_width: 6
+end
+```
+
+### Resource 3: Products (JSON Editors and Advanced Layout)
+
+```ruby
+Kabk.register(name: "products", table: Product) do
+  title en: "Products Catalog", fa: "محصولات و کالاها"
+  icon "Package"
+  api_path "/admin/api/products"
+  group "Store & Services"
+  order 4
+  searchable_fields [:title, :sku]
+
+  field :id, type: :number, form_type: :number, primary_key: true, hidden_in_form: true
+  field :title, type: :string, form_type: :text, required: true, col_width: 8
+  field :sku, type: :string, form_type: :text, required: true, col_width: 4
+  
+  field :price, type: :number, form_type: :number, required: true, col_width: 6, validation: { min: 0, max: 1000000000 }
+  field :stock, type: :number, form_type: :number, required: true, col_width: 6, validation: { min: 0 }
+
+  field :specs_json, type: :json, form_type: :json_editor, hidden_in_table: true, accordion: true, default_value: {
+    weight_kg: 1.2,
+    brand: "Acme Corp",
+    warranty_months: 24,
+    dimensions: { length: 30, width: 20, height: 10 }
+  }
+
+  field :status, type: :string, form_type: :select, display_as: "badge", options: [
+    { label: { en: "In Stock", fa: "موجود در انبار" }, value: "in_stock", color: "green" },
+    { label: { en: "Low Stock", fa: "موجودی محدود" }, value: "low_stock", color: "amber" },
+    { label: { en: "Out of Stock", fa: "ناموجود" }, value: "out_of_stock", color: "red" }
+  ]
+end
+```
+
+### Resource 4: News (Relations, File Uploads, WYSIWYG)
+
+This entity brings it all together by referencing `users` and `categories`, and handling complex file configurations.
+
+```ruby
+Kabk.register(name: "news_item", table: NewsItem) do
+  title en: "News & Announcements", fa: "اخبار و اطلاعیه‌ها"
+  icon "Newspaper"
+  api_path "/admin/api/news"
+  group "Content Management"
+  order 1
+  concurrency_field "updated_at"
+  
+  searchable_fields [:title, :content]
+  filterable_fields [:published, :category_ids]
+
+  field :id, type: :number, form_type: :number, primary_key: true, hidden_in_form: true, col_width: 2
+  
+  field :title, type: :string, form_type: :text, required: true, col_width: 12, validation: {
+    min_length: 5, max_length: 150,
+    custom_message: { en: "Title 5-150 chars", fa: "عنوان بین ۵ تا ۱۵۰ کاراکتر" }
+  }
+
+  # Many-to-One Relation (Author -> User)
+  field :author_id, type: :relation, form_type: :relation_select, required: true, col_width: 6, relation: {
+    resource: "users", cardinality: :many_to_one,
+    value_field: "id", label_field: "full_name",
+    display_key: "author_id_display", fetch_endpoint: "/admin/api/users",
+    search_param: "search", debounce_ms: 300, per_page: 20
+  }
+
+  # Many-to-Many Relation (News -> Categories)
+  field :category_ids, type: :relation, form_type: :multiselect, required: true, col_width: 6, relation: {
+    resource: "categories", cardinality: :many_to_many,
+    value_field: "id", label_field: "title",
+    display_key: "category_ids_display", fetch_endpoint: "/admin/api/categories"
+  }
+
+  # Single Image Upload (with constraints)
+  field :cover_image, type: :file, form_type: :image_single, display_as: "thumbnail", nullable: true, col_width: 6, upload_config: {
+    allowed_extensions: ["jpg", "jpeg", "png", "webp"],
+    max_size_mb: 3
+  }
+
+  # Multi-Image Gallery
+  field :gallery, type: :array, form_type: :image_multi, hidden_in_table: true, col_width: 6, upload_config: {
+    allowed_extensions: ["jpg", "png", "webp"], max_size_mb: 5
+  }
+
+  field :content, type: :string, form_type: :wysiwyg, hidden_in_table: true, accordion: true, required: true
+
+  field :published, type: :boolean, form_type: :switch, display_as: "boolean_icon", default_value: false
+  
+  field :publish_date, type: :datetime, form_type: :datetime, nullable: true, col_width: 6, depends_on: {
+    field: "published", value: true
+  }, validation: { min_date: "2020-01-01T00:00:00Z" }
+
+  field :updated_at, type: :datetime, form_type: :datetime, readonly: true, hidden_in_form: true
+end
+```
+
+---
+
+## 3. What to do next?
+Now that the schema and DSL have been mapped out, simply run your Roda application and navigate to `/admin` in your browser. The Simurgh panel will dynamically parse this metadata and render all interactive UI components, relationships, validations, and custom fonts.