roda-kabk 0.1.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 29d71b61867e52a48284e539f00194c7094a5a6b3c80282f0a4ed6702085132b
+  data.tar.gz: 3432f771d7e78f564bf86bf5be72e636725b92185180940d1cce07e71fdfeb8a
+SHA512:
+  metadata.gz: 8a0ebee193374a27891b1416081a3fd60c2039eab8f8d1886fe579676da0787105efbe4921dcd0ee6606d77c6bfe04cee1e3e352ddbd57adfa7da15b613cf1fd
+  data.tar.gz: 0d3510f11f3becae6b999b1a8a5e2d9458b553d971877e527867625c2038da8746b0de3cc388acd05a5d9f7587e6a9507fa1d1dea191658a4cb06c0ec63e49a4

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,88 @@
+PATH
+  remote: .
+  specs:
+    roda-kabk (0.1.2)
+      kabk (~> 0.1.2)
+      roda (~> 3.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    base64 (0.3.0)
+    bigdecimal (4.1.2)
+    concurrent-ruby (1.3.8)
+    csv (3.3.6)
+    diff-lcs (1.6.2)
+    jwt (2.10.3)
+      base64
+    kabk (0.1.2)
+      concurrent-ruby (~> 1.1)
+      csv
+      jwt (~> 2.7)
+      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
+  base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
+  bigdecimal (4.1.2) sha256=53d217666027eab4280346fba98e7d5b66baaae1b9c3c1c0ffe89d48188a3fbd
+  concurrent-ruby (1.3.8) sha256=b2f1be836e968ccc78ccfce277ea79c72a88633f22306782c16ff23fb415d1e1
+  csv (3.3.6) sha256=aba61e7e507a66f03d45cb1f3c4b6359861c3504038b422962875dce099e4456
+  diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
+  jwt (2.10.3) sha256=e4d9352fbc7309b1a7448c7dd713dfe4d8c47077af80759cdbed8f878ea0b484
+  kabk (0.1.2)
+  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.1.2)
+  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,188 @@
+<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) — seamlessly binding Roda applications to the Simurgh Panel protocol (v1.6.0) for schema-driven dynamic REST APIs without duplicating backend logic.
+
+---
+
+## Features
+
+- **Embedded Simurgh Panel UI**: Bundles and serves the pre-built single-page admin dashboard SPA directly at `mount_at` (`/api/admin`) with embedded schema injection.
+- **Generic REST Engine**: Auto-generates full CRUD, search, multi-field filtering, sorting, and pagination for registered Sequel models.
+- **Pluggable File Uploads**: Seamless integration with **Shrine**, ActiveStorage, or custom storage handlers via configurable procs.
+- **Authentication & Security**: Integrated JWT authentication (`login`, `refresh`, `me`, `change-password`) and Role-Based Access Control (RBAC).
+- **Optimistic Concurrency Control (OCC)**: Built-in support for preventing concurrent record overwrite conflicts (`updated_at` / `version`).
+- **Data Export**: Exposes CSV and XLSX export endpoints out of the box (`/export`).
+
+---
+
+## Installation
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem 'roda-kabk'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+---
+
+## Quick Start
+
+```ruby
+require 'roda'
+require 'sequel'
+require 'kabk'
+require 'roda/plugins/kabk'
+
+# 1. Setup DB and Sequel Model
+DB = Sequel.sqlite
+DB.create_table :articles do
+  primary_key :id
+  String :title, null: false
+  String :content
+  DateTime :updated_at
+end
+
+class Article < Sequel::Model; end
+
+# 2. Register Entity with Kabk
+Kabk.register(name: "article", table: Article) do
+  title "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, calendar: :jalali
+end
+
+# 3. Mount Kabk Plugin in Roda
+class App < Roda
+  plugin :kabk,
+         mount_at: "/api/admin",
+         serve_ui: true,
+         auth_strategy: Kabk::Auth::JwtStrategy.new(secret: ENV.fetch("JWT_SECRET", "super_secret_key")),
+         login_handler: ->(username, password) {
+           # Fetch user from DB and verify password
+           # return user_data hash if valid, nil otherwise
+           user = User.first(email: username)
+           return nil unless user && user.authenticate(password)
+           { id: user.id, username: user.email, role: user.role }
+         },
+         change_password_handler: ->(user_context, old_pw, new_pw) {
+           # Verify old password and save new password
+           user = User[user_context[:id]]
+           raise Kabk::InvalidOldPasswordError.new(fields: { old_password: ["Incorrect password"] }) unless user.authenticate(old_pw)
+           user.update(password: new_pw)
+         },
+         upload_handler: ->(file_param, req) {
+           # Integration point for Shrine / ActiveStorage
+           {
+             url: "/uploads/#{file_param[:filename]}",
+             file_name: file_param[:filename],
+             size: file_param[:tempfile].size,
+             mime_type: file_param[:type]
+           }
+         }
+
+  route do |r|
+    # Exposes Dashboard UI, Auth, CRUD, Export, and Upload endpoints under /api/admin
+    r.kabk
+  end
+end
+```
+
+---
+
+## Configuration Reference
+
+The `plugin :kabk` method accepts the following options:
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `mount_at` | `String` | `"/api/admin"` | Base URI path under which all Kabk admin endpoints and UI are mounted. |
+| `serve_ui` | `Boolean` | `true` | Serves the bundled Simurgh Panel single-page dashboard UI directly at `mount_at`. |
+| `system_config` | `Hash` / `NilClass` | `nil` | Custom system branding and localization settings (overrides default locale/title). |
+| `auth_strategy` | `Kabk::Auth::JwtStrategy` / `NilClass` | `nil` | Authentication strategy object. Set to `nil` to disable auth for development. |
+| `upload_handler` | `Proc` / `Callable` | `nil` | Custom file upload handler block/callable. Processes uploaded file params. |
+
+---
+
+## File Upload Integration (Shrine Example)
+
+You can connect **Shrine** directly using the `upload_handler` option:
+
+```ruby
+plugin :kabk,
+       mount_at: "/api/admin",
+       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, the endpoint returns an `HTTP 400 Bad Request` with error code `BAD_REQUEST`.
+
+---
+
+## Endpoints Reference
+
+All endpoints are exposed under the configured `mount_at` prefix (e.g. `/api/admin`):
+
+### Authentication
+- `POST /api/admin/auth/login` — Authenticates user credentials & returns JWT access/refresh tokens.
+- `POST /api/admin/auth/refresh` — Generates new access token from refresh token.
+- `GET /api/admin/auth/me` — Returns current authenticated user context.
+- `POST /api/admin/auth/logout` — Revokes active session.
+- `POST /api/admin/auth/change-password` — Updates user password (requires `old_password` verification).
+
+### Resource Operations (Generic REST)
+For any registered entity `plural_name` (e.g., `/articles`, `/users`):
+- `GET /api/admin/:plural_name` — List records (supports `page`, `per_page`, `sort`, `search`, `filter[field]`).
+- `GET /api/admin/:plural_name/:id` — Retrieve single record details.
+- `POST /api/admin/:plural_name` — Create new record.
+- `PUT /api/admin/:plural_name/:id` — Update record (with Optimistic Concurrency Control).
+- `DELETE /api/admin/:plural_name/:id` — Delete record.
+- `GET /api/admin/:plural_name/export` — Export data in `csv` or `xlsx` format (`?format=xlsx`).
+
+### Media Uploads
+- `POST /api/admin/uploads` — Upload file via multipart/form-data.
+
+---
+
+## 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,227 @@
+# 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, jalali calendars, 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 (like Sahel and Lalezar).
+
+```ruby
+require 'roda'
+require 'roda/plugins/kabk'
+
+class AdminApp < Roda
+  plugin :kabk,
+         mount_at: "/api/admin",
+         system_config: {
+           title: { fa: "پنل مدیریت سیمرغ", en: "Simurgh Panel" },
+           logo_url: "https://images.unsplash.com/photo-1618005182384-a83a8bd57fbe?w=100&h=100&fit=crop&crop=faces",
+           default_locale: "fa",
+           supported_locales: ["fa", "en"],
+           direction: "rtl",
+           custom_fonts: [
+             {
+               name: "Sahel",
+               url: "https://cdn.jsdelivr.net/gh/rastikerdar/sahel-font@v3.4.0/dist/Sahel.woff2",
+               format: "woff2",
+               label: { fa: "ساحل (فارسی)", en: "Sahel (Persian)" }
+             },
+             {
+               name: "Lalezar",
+               url: "https://cdn.jsdelivr.net/gh/rastikerdar/lalezar-font@v1.0.0/dist/Lalezar.woff2",
+               format": "woff2",
+               label: { fa: "لاله‌زار (عنوان فانتزی)", en: "Lalezar (Display)" }
+             }
+           ],
+           custom_font_sizes: [
+             { size: "15px", label: { fa: "عادی ویژه", en: "Special Normal" } },
+             { size: "20px", label: { fa: "برجسته متوسط", en: "Highlighted Medium" } },
+             { size: "32px", label: { fa: "تیتر بزرگ", en: "Hero Banner" } }
+           ]
+         },
+         auth_strategy: Kabk::Auth::JwtStrategy.new(secret: ENV.fetch("JWT_SECRET", "secret")),
+         login_handler: ->(username, password) {
+           user = User.first(email: username)
+           return nil unless user && user.authenticate(password)
+           { id: user.id, username: user.email, role: user.role }
+         },
+         change_password_handler: ->(user_context, old_pw, new_pw) {
+           user = User[user_context[:id]]
+           raise Kabk::InvalidOldPasswordError.new(fields: { old_password: ["Incorrect password"] }) unless user.authenticate(old_pw)
+           user.update(password: new_pw)
+         }
+
+  route do |r|
+    r.kabk
+  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 fa: "مدیریت کاربران", en: "User Directory"
+  icon "Users"
+  api_path "/api/admin/users"
+  group "دسترسی و کاربران"
+  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: { fa: "فرمت ایمیل معتبر نیست یا قبلاً ثبت شده است", en: "Email invalid or taken" }
+  }
+
+  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: { fa: "مدیر کل", en: "Administrator" }, value: "admin", color: "purple" },
+    { label: { fa: "ویرایشگر", en: "Editor" }, value: "editor", color: "blue" },
+    { label: { fa: "نویسنده", en: "Author" }, value: "author", color: "emerald" },
+    { label: { fa: "مشاهده‌کننده", en: "Viewer" }, 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, calendar: :jalali, nullable: true
+  field :created_at, type: :date, form_type: :date, calendar: :jalali, readonly: true, hidden_in_form: true
+end
+```
+
+### Resource 2: Categories (Simple Text and Badges)
+
+```ruby
+Kabk.register(name: "categories", table: Category) do
+  title fa: "دسته‌بندی‌ها", en: "Categories"
+  icon "Tags"
+  api_path "/api/admin/categories"
+  group "مدیریت محتوا"
+  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 fa: "محصولات و کالاها", en: "Products Catalog"
+  icon "Package"
+  api_path "/api/admin/products"
+  group "فروشگاه و خدمات"
+  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 }
+
+  # Using JSON Editor with accordion and default nested structures
+  field :specs_json, type: :json, form_type: :json_editor, hidden_in_table: true, accordion: true, default_value: {
+    weight_kg: 1.2,
+    brand: "Shayan Group",
+    warranty_months: 24,
+    dimensions: { length: 30, width: 20, height: 10 }
+  }
+
+  field :status, type: :string, form_type: :select, display_as: "badge", options: [
+    { label: { fa: "موجود در انبار", en: "In Stock" }, value: "in_stock", color: "green" },
+    { label: { fa: "موجودی محدود", en: "Low Stock" }, value: "low_stock", color: "amber" },
+    { label: { fa: "ناموجود", en: "Out of Stock" }, value: "out_of_stock", color: "red" }
+  ]
+end
+```
+
+### Resource 4: News (Relations, File Uploads, WYSIWYG, Jalali Date)
+
+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 fa: "اخبار و اطلاعیه‌ها", en: "News & Announcements"
+  icon "Newspaper"
+  api_path "/api/admin/news"
+  group "مدیریت محتوا"
+  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: { fa: "عنوان بین ۵ تا ۱۵۰ کاراکتر", en: "Title 5-150 chars" }
+  }
+
+  # 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: "/api/admin/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: "/api/admin/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
+  
+  # Dependent Field with Jalali Calendar
+  field :publish_date, type: :datetime, form_type: :datetime, calendar: :jalali, 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, calendar: :jalali, 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 `/api/admin` in your browser. The Simurgh panel will dynamically parse this metadata and render all interactive UI components, Jalali calendars, relationships, validations, and custom fonts.

data/examples/app.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "roda"
+require "sequel"
+require "logger"
+
+# Setup memory database
+DB = Sequel.sqlite
+DB.extension :pagination
+DB.logger = Logger.new($stdout)
+
+# Create tables matching Schema_Sample.json entities
+DB.create_table :users do
+  primary_key :id
+  String :full_name
+  String :email
+  String :avatar
+  String :role, default: "editor"
+  String :bio
+  TrueClass :is_active, default: true
+  DateTime :created_at
+  DateTime :updated_at
+end
+
+DB.create_table :categories do
+  primary_key :id
+  String :title
+  String :slug
+  String :color_code
+end
+
+DB.create_table :news_items do
+  primary_key :id
+  String :title
+  Integer :author_id
+  String :category_ids # Simplified many-to-many as JSON string or comma-separated for SQLite
+  String :cover_image
+  String :gallery
+  String :content
+  TrueClass :published, default: false
+  DateTime :publish_date
+  DateTime :updated_at
+  DateTime :created_at
+end
+
+# Require Kabk core
+$LOAD_PATH.unshift File.expand_path("../../kabk/lib", __dir__)
+require "kabk"
+
+# Define Sequel Models
+class User < Sequel::Model; end
+class Category < Sequel::Model; end
+class NewsItem < Sequel::Model; end
+
+# Register Resources using DSL
+Kabk.register(name: "user", table: User) do
+  title fa: "مدیریت کاربران", en: "User Directory"
+  plural_name "users"
+  icon "Users"
+  api_path "/api/admin/users"
+  searchable_fields ["full_name", "email"]
+  sortable_fields ["id", "full_name", "role", "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: { unique: true }
+  field :avatar, type: :file, form_type: :image_single, display_as: :thumbnail
+  field :role, type: :string, form_type: :select, required: true, display_as: :badge, default_value: "editor"
+  field :bio, type: :string, form_type: :textarea, hidden_in_table: true, accordion: true
+  field :is_active, type: :boolean, form_type: :switch, display_as: :boolean_icon, default_value: true
+  field :created_at, type: :date, form_type: :date, calendar: :jalali, readonly: true, hidden_in_form: true
+end
+
+Kabk.register(name: "category", table: Category) do
+  title fa: "دسته‌بندی‌ها", en: "Categories"
+  plural_name "categories"
+  icon "Tags"
+  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
+  field :slug, type: :string, form_type: :text, required: true
+  field :color_code, type: :string, form_type: :text, display_as: :badge
+end
+
+Kabk.register(name: "news_item", table: NewsItem) do
+  title fa: "اخبار و اطلاعیه‌ها", en: "News & Announcements"
+  plural_name "news"
+  icon "Newspaper"
+  searchable_fields ["title", "content"]
+  concurrency_field "updated_at"
+
+  field :id, type: :number, form_type: :number, primary_key: true, hidden_in_form: true
+  field :title, type: :string, form_type: :text, required: true
+  field :author_id, type: :relation, form_type: :relation_select, relation: { resource: "user", cardinality: "many_to_one", value_field: "id", label_field: "full_name" }
+  field :category_ids, type: :relation, form_type: :multiselect, relation: { resource: "category", cardinality: "many_to_many", value_field: "id", label_field: "title" }
+  field :cover_image, type: :file, form_type: :image_single, display_as: :thumbnail
+  field :content, type: :string, form_type: :wysiwyg, hidden_in_table: true, accordion: true
+  field :published, type: :boolean, form_type: :switch, display_as: :boolean_icon
+  field :publish_date, type: :datetime, form_type: :datetime, calendar: :jalali, depends_on: { field: "published", value: true }
+  field :updated_at, type: :datetime, form_type: :datetime, calendar: :jalali, readonly: true, hidden_in_form: true
+end
+
+# Seed some mock data
+User.create(full_name: "Admin User", email: "admin@example.com", role: "admin")
+User.create(full_name: "Reza Mohammadi", email: "reza@example.com", role: "editor")
+Category.create(title: "Announcements", slug: "announcements")
+Category.create(title: "Events", slug: "events")
+NewsItem.create(title: "First Post", author_id: 2, category_ids: "[1,2]", content: "Hello World", updated_at: Time.now)
+
+# Main App using Roda
+class App < Roda
+  # Setup plugin with mock JWT Strategy
+  plugin :kabk, 
+         mount_at: "/api/admin",
+         auth_strategy: Kabk::Auth::JwtStrategy.new(secret: "test_secret"),
+         system_config: { logo_url: "/kabk_logo.png" }
+
+  route do |r|
+    # This mounts all the standard protocol endpoints and UI automatically under /api/admin
+    r.kabk
+    
+    r.root do
+      "Welcome to Kabk Simurgh Protocol API."
+    end
+  end
+end

data/examples/config.ru

@@ -0,0 +1,2 @@
+require_relative "app"
+run App.freeze.app