Control Dojo v1.1.0 — The 5.9 FP1 Compatibility Update

Author: EsSwart

CHANGELOG.md

@@ -0,0 +1,94 @@
+# Changelog
+
+All notable changes to Control Dojo will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0] - The 5.9 Compatibility Update
+
+### Added
+
+#### Platform & Infrastructure
+- **K2 Five 5.9 FP1 Compatibility**: Full compatibility with K2 Five 5.9 FP1, fully tested and aligned with the latest K2 release
+- **Express v5 Upgrade**: Upgraded backend server to Express v5 for improved performance and modern features
+- **Flowbite v4 Integration**: Upgraded to Flowbite v4 for enhanced UI components and improved theme support
+- **Tailwind CSS v4**: Upgraded to Tailwind CSS v4 with new build tooling for better performance
+- **Validation Error Popup Component**: New dedicated ValidationErrorPopup component for design-time validation feedback in the Inspector
+
+#### Documentation
+- **Accessibility Guide**: New comprehensive accessibility guide (`docs/Accessibility.md`) covering WCAG 2.1 Level AA standards, keyboard navigation, ARIA patterns, screen reader support, error handling, focus management, and complete implementation examples with best practices
+- **Manifest Configuration Guide**: Major enhancements including:
+  - **Control Data Type Declaration**: Complete documentation for `datatypes` array that enables field binding and Change Control functionality in K2 Designer, with full list of 20+ supported data types (AutoGuid, Date, DateTime, Decimal, File, Guid, Hyperlink, Image, Label, Memo, MultiValue, Number, Text, Time, Xml, YesNo, etc.)
+  - **Property Categories**: Documentation for grouping properties in K2 designer's property panel with custom category support
+  - **Design-time Property Validation**: Complete guide for `validationpattern` and `validationmessage` fields that provide regex-based validation in K2 Designer (design-time only, not runtime)
+  - **Int Property Type**: Documentation for new `int` property type with built-in 32-bit range validation and default error messages
+  - **ControlExpression Support**: Documentation explaining how ControlExpression works (uses Value property, no separate get/set methods required)
+  - **Escaping Rules**: Documentation for property metadata character escaping rules to prevent manifest parsing errors
+- **Standard Properties Guide**: Significant updates including:
+  - **TabIndex Property**: Complete implementation patterns with code examples for keyboard navigation and tab order control
+  - **ControlExpression Support**: Documentation explaining that ControlExpression uses Value property's getter/setter (no separate methods needed)
+  - **Width Validation Rules**: Critical documentation about width property limitations (no "auto" support, validation requirements, valid/invalid formats, error messages)
+  - **Complete Implementation Templates**: Updated templates showing all standard properties including TabIndex
+- **Form View Validation Guide**: Enhanced with design-time property validation section explaining the distinction between design-time validation (via manifest) and runtime validation (via Validate method)
+- **Data Binding Guide**: Added critical limitation documentation - K2 controls can only have one ListData property per control, with explanation of SMO binding restrictions
+- **Overview Guide**: Updated with accessibility section link, file upload/download control creation guidance, and updated Drag & Drop features list
+
+#### Control Enhancements
+- **Drag & Drop**: 
+  - **File Download**: Added SmartObject file download support via a new action container.
+  - **Icon-Only Mode**: New "ShowInformation" toggle for space-constrained layouts.
+  - **Visual Overhaul**: Smoother drag animations and improved error state indicators.
+- **Arabic Calendar**: Added `TabIndex` support and enhanced keyboard navigation for better accessibility.
+- **Button List**: Added `MaxItems` property (int) with built-in design-time validation to limit item display.
+- **CAPTCHA Box**: Improved documentation regarding CORS handling and production deployment.
+
+#### UI/UX Improvements
+- **Inspector Component**: Major refactoring and enhancements including TabIndex helper UI with increment/decrement buttons and value display, improved theme support, better validation feedback, and Flowbite integration
+- **Wizard Component**: Major updates and enhancements including design-time validation functionality, width auto limitation validation (blocks "auto" as initial value), data type support, int property type support with ValidationMessage, and improved validation feedback
+- **App Component**: Updates to main application component with improved navigation and theme support
+- **Documents Component**: Updates to documentation viewer with improved page navigation and document link handling
+- **Home Component**: Updates to home page with improved layout and content
+- **ValidationErrorPopup Component**: New component for design-time validation feedback with theme support
+- **File Generator**: Updates to control file generation utility with improved code generation
+- **Styles**: Updates to main CSS file with improved theming and Flowbite integration
+
+### Changed
+
+#### Platform
+- **Express v5 Upgrade**: Upgraded from Express v4 to Express v5 for improved performance and modern async/await support
+- **Flowbite v4 Upgrade**: Upgraded from Flowbite v3 to Flowbite v4 for enhanced UI components, improved theming, and better component integration
+- **Tailwind CSS v4**: Upgraded from Tailwind CSS v3 to v4 with new @tailwindcss/postcss and @tailwindcss/vite packages for better build performance
+- **Archiver Upgrade**: Upgraded archiver package for improved ZIP generation
+- **Vite Upgrade**: Updated to latest Vite version for improved build performance
+- **Package Updates**: Updated all dependencies to latest compatible versions for security and performance
+- **Build Configuration**: Updates to PostCSS and Vite configuration for optimized builds
+- **Base Control Script**: Updates to k2-base-control.js with code improvements
+
+#### Documentation
+- **Standard Properties Guide**: Enhanced with TabIndex implementation details, ControlExpression documentation, and comprehensive width validation rules
+- **Manifest Configuration Guide**: Major updates with data types documentation, property categories, validation fields, int type documentation, and ControlExpression support
+- **Form View Validation Guide**: Enhanced with design-time property validation section explaining validationpattern and validationmessage
+- **Data Binding Guide**: Updated with ListData limitation documentation
+- **Overview Guide**: Updated with accessibility section and file upload/download guidance
+### Technical Notes
+
+#### Breaking Changes
+- None
+
+#### Migration
+- No manual migration steps required
+
+#### Requirements
+- Node.js 14+ and a modern web browser
+
+---
+
+## [1.0.0] - First Public Release
+
+### Added
+- Initial release of Control Dojo
+- Control Inspector for debugging existing controls
+- Control Wizard for creating new controls
+- Support for multiple control examples
+- ZIP generation for control packages

Controls/Arabic Calendar/README.md

@@ -42,6 +42,7 @@ The K2 Arabic Calendar control is designed specifically for Arabic-speaking user
 | **Width** | Number | `""` | Number or string with unit | Control width |
 | **IsVisible** | Boolean | `true` | `true`, `false` | Control visibility |
 | **IsEnabled** | Boolean | `true` | `true`, `false` | Control interactivity |
+| **TabIndex** | String | `"0"` | Any string | Tab order for keyboard navigation |
 
 ### Core Properties
 
@@ -161,6 +162,15 @@ The K2 Arabic Calendar control is designed specifically for Arabic-speaking user
   control.IsEnabled = false; // Disable control
   ```
 
+#### TabIndex
+- **Type**: String
+- **Default**: `"0"`
+- **Description**: Tab order index for keyboard navigation
+- **Usage**:
+  ```javascript
+  control.TabIndex = "1"; // Set tab order
+  ```
+
 ## Events
 
 ### Quick Reference
@@ -171,6 +181,7 @@ The K2 Arabic Calendar control is designed specifically for Arabic-speaking user
 | **Focus** | Control receives focus | None | Yes |
 | **Blur** | Control loses focus | None | Yes |
 | **ValidationError** | Invalid date input | `{ message: string, value: string }` | Yes |
+| **Rendered** | Control finishes initial rendering | None | Yes |
 
 ### Event Details
 

Controls/Arabic Calendar/designtime_logic.js

@@ -90,11 +90,20 @@ if (!window.customElements.get('arabic-calendar')) {
     safeRaisePropertyChanged(this, 'IsReadOnly');
   }
 
+  get TabIndex() { return this._tabIndex; }
+  set TabIndex(val) {
+    this._tabIndex = val || "0";
+    if (this._hasRendered && this.input && this.input.length > 0) {
+      this.input[0].setAttribute("tabindex", this._tabIndex);
+    }
+    safeRaisePropertyChanged(this, 'TabIndex');
+  }
+
   // Simplified template for designtime preview only (no popup or interactivity)
   _TEMPLATE = `
       <div class="container empty">
         <div class="input-wrap">
-          <input type="text" class="date-input" placeholder="اضغط الزر لاختيار التاريخ" readonly aria-haspopup="dialog" aria-expanded="false" aria-controls="k2-cal-popup"/>
+          <input type="text" class="date-input" tabindex="${this._tabIndex}" placeholder="اضغط الزر لاختيار التاريخ" readonly aria-haspopup="dialog" aria-expanded="false" aria-controls="k2-cal-popup"/>
           <span class="floating-watermark">اضغط الزر لاختيار التاريخ</span>
           <div class="icon-background"></div>
         </div>
@@ -115,6 +124,7 @@ if (!window.customElements.get('arabic-calendar')) {
   _isVisible = true;
   _isEnabled = true;
   _isReadOnly = false;
+  _tabIndex = "0";
 
   constructor() { super(); }
 
@@ -334,6 +344,7 @@ if (!window.customElements.get('arabic-calendar')) {
     this.IsVisible = this._isVisible;
     this.IsEnabled = this._isEnabled;
     this.IsReadOnly = this._isReadOnly;
+    this.TabIndex = this._tabIndex;
     if (this._value) this.container.classList.remove('empty');
     else this.container.classList.add('empty');
 

Controls/Arabic Calendar/manifest.json

@@ -17,12 +17,15 @@
   "displayName": "Arabic Calendar",
   "tagName": "arabic-calendar",
   "valuePropertyID": "Value",
+  "datatypes": ["DateTime", "Date"],
   "supports": [
     "Value",
     "Width",
     "IsVisible",
     "IsEnabled",
-    "IsReadOnly"
+    "IsReadOnly",
+    "TabIndex",
+    "ControlExpression"
   ],
   "events": [
     {

Controls/Arabic Calendar/runtime_logic.js

@@ -119,13 +119,22 @@ if (!window.customElements.get('arabic-calendar')) {
     this.setAttribute('dateformat', val);
     safeRaisePropertyChanged(this, 'DateFormat');
   }
+
+  get TabIndex() { return this._tabIndex; }
+  set TabIndex(val) {
+    this._tabIndex = val || "0";
+    if (this._hasRendered && this.input && this.input.length > 0) {
+      this.input[0].setAttribute("tabindex", this._tabIndex);
+    }
+    safeRaisePropertyChanged(this, 'TabIndex');
+  }
 
 
   // Template without styles (CSS is external)
   _TEMPLATE = `
       <div class="container empty">
         <div class="input-wrap">
-          <input type="text" class="date-input" aria-haspopup="dialog" aria-expanded="false" aria-controls="k2-cal-popup"/>
+          <input type="text" class="date-input" tabindex="${this._tabIndex}" aria-haspopup="dialog" aria-expanded="false" aria-controls="k2-cal-popup"/>
           <span class="floating-watermark">اضغط الزر لاختيار التاريخ</span>
           <div class="icon-background"></div>
         </div>
@@ -170,6 +179,7 @@ if (!window.customElements.get('arabic-calendar')) {
   _isValid = true;
   _logPrefix = '[arabic-calendar]';
   _isProgrammaticValue = false; // Flag to track programmatically set values
+  _tabIndex = "0";
 
   // Picker state management
   _currentView = 'days'; // 'days', 'months', 'years'
@@ -222,6 +232,7 @@ if (!window.customElements.get('arabic-calendar')) {
     this.Width = this._width;
     this.IsVisible = this._isVisible;
     this.IsEnabled = this._isEnabled;
+    this.TabIndex = this._tabIndex;
     if (this._value && this._value.trim() !== '') {
       this.container.classList.remove('empty');
       // Hide watermark when there's a value

Controls/Button List/README.md

@@ -46,7 +46,7 @@ Button List/
 |----------|------|---------|-------------|
 | **Value** | String | `null` | The value of the currently selected button. Updates automatically when a button is clicked. |
 | **List** | ListData | `[]` | Array of button items. Each item should have `display`, `value`, and optionally `icon` fields. Supports both static JSON and SmartObject binding. |
-| **MaxItems** | String | `"0"` | Maximum number of items to display (0 = unlimited). Accepts numeric values as strings. |
+| **MaxItems** | Int | `0` | Maximum number of items to display (0 = unlimited). Uses `int` type with built-in range validation plus a custom regex to enforce zero or positive integers. |
 | **ButtonLayout** | String | `"horizontal"` | Layout mode: `"horizontal"`, `"vertical"`, or `"grid"` |
 | **ButtonSize** | String | `"medium"` | Button size: `"small"`, `"medium"`, or `"large"` |
 | **ButtonStyle** | String | `"normal"` | Button style matching K2 button control styles: `"normal"`, `"main"`, `"quiet"`, or `"destructive"` |
@@ -78,20 +78,27 @@ All properties support the following fields:
 |-------|------|----------|-------------|
 | `id` | String | Yes | Unique property identifier (used in code) |
 | `friendlyname` | String | Yes | Human-readable name shown in property panel |
-| `type` | String | Yes | Property data type: `"string"`, `"bool"`, `"text"`, `"listdata"` |
+| `type` | String | Yes | Property data type: `"string"`, `"bool"`, `"int"`, `"text"`, `"listdata"` |
 | `initialvalue` | String | Yes | Default value for the property |
 | `refreshdisplay` | String | Yes | Whether changes trigger display refresh (`"true"` or `"false"`) |
 | `changesdisplay` | Boolean | Yes | Whether changes affect visual appearance |
 | `inputlength` | String | No | Maximum input length for string properties |
 | `description` | String | No | Property description/tooltip shown in designer |
 | `category` | String | No | Property category for grouping (e.g., `"Detail"` for data properties) |
 
+### Design-time validation
+
+- `MaxItems` now uses the new `int` property type. The default `int` validation blocks non-numeric values and values outside the 32-bit range.
+- Custom validation is configured with `validationpattern` and `validationmessage`. For `MaxItems`, the pattern `^0$|^[1-9]\\d*$` enforces zero or positive integers and the message `Must be zero or a positive integer.` is displayed when validation fails.
+- If you set only a pattern or only a message, the missing piece falls back to the default `int` behavior.
+
 ## Events
 
 | Event | Description |
 |-------|-------------|
 | **OnChanged** (friendly name: "Changed") | Fired when a button is clicked and the Value property changes. Contains the new value, old value, and selected item. **Use this event to transfer the selected value to other controls.** |
-| **OnButtonClick** (friendly name: "Button Clicked") | Fired when any button is clicked. Contains the button item details (display, value, index) and previous selection state. |
+| **OnButtonClick** (friendly name: "Clicked") | Fired when any button is clicked. Contains the button item details (display, value, index) and previous selection state. |
+| **Rendered** | Fired when the control finishes initial rendering. Indicates the control is ready for interaction. |
 
 ## List Data Structure
 
@@ -148,10 +155,32 @@ When binding to a SmartObject:
 | Method | Description | Parameters | Return Type |
 |--------|-------------|------------|-------------|
 | **clearSelection** | Clears the current selection | None | None |
-| **selectById** | Selects a button by its ID (value property) | `id` (String) | None |
-| **selectByText** | Selects a button by its display text | `text` (String) | None |
+| **selectById** | Selects a button by its ID (value property). Also accepts `selectByValue` as an alias. | `id` (String) - The value property of the button to select | None |
+| **selectByText** | Selects a button by its display text. Also accepts `selectByIndex` as an alias (for backward compatibility, but now selects by text, not index). | `text` (String) - The display text of the button to select | None |
 | **refresh** | Forces a re-render of the control | None | None |
 
+### Method Execution via K2 Rules
+
+Methods can be called via K2 rules using the `execute` method:
+
+```javascript
+// Clear selection
+control.execute({ methodName: "clearSelection" });
+
+// Select by ID/value
+control.execute({ methodName: "selectById", value: "1" });
+// or
+control.execute({ methodName: "selectByValue", value: "1" });
+
+// Select by text
+control.execute({ methodName: "selectByText", text: "Home" });
+// or (backward compatibility)
+control.execute({ methodName: "selectByIndex", index: "Home" });
+
+// Refresh
+control.execute({ methodName: "refresh" });
+```
+
 ### Method Examples
 
 ```javascript

Controls/Button List/manifest.json

@@ -7,8 +7,8 @@
   "displayName": "Button List",
   "tagName": "button-list",
   "description": "A flexible button list control that displays a collection of interactive buttons with customizable styling, layout options, and icon support. Supports both static data and SmartObject binding for dynamic content.",
+  "datatypes": ["Text"],
   "supports": [
-    "lo", 
     "Width", 
     "Height",
     "Value", 
@@ -40,23 +40,16 @@
       "initialvalue": "55px",
       "changesdisplay": true
     },
-    {
-      "id": "List",
-      "refreshdisplay": "true",
-      "friendlyname": "List Items",
-      "type": "listdata",
-      "category": "Detail",
-      "initialvalue": "[{\"display\": \"Item 1\", \"value\": \"1\"},{\"display\": \"Item 2\",\"value\": \"2\"}]"
-    },
     {
       "id": "MaxItems",
       "refreshdisplay": "true",
       "friendlyname": "Max Items",
-      "type": "string",
-      "inputlength": "50",
-      "initialvalue": "0",
+      "type": "int",
+      "initialvalue": 0,
+      "validationpattern": "^0$|^[1-9]\\d*$",
+      "validationmessage": "Must be zero or a positive integer.",
       "changesdisplay": true,
-      "description": "Maximum number of items to display (0 = unlimited). Accepts numeric values as strings."
+      "description": "Maximum number of items to display (0 = unlimited). Uses int type with default and custom validation."
     },
     {
       "id": "ButtonLayout",

Controls/CAPTCHA Box/README.md

@@ -34,6 +34,13 @@ A customizable CAPTCHA box for Control Dojo that provides bot protection using o
 | `ErrorMessage` | String | `""` | Message shown on verification failure (localized) |
 | `AutoRefresh` | Boolean | `true` | Whether to automatically refresh CAPTCHA on verification failure |
 | `Theme` | String | `"light"` | Visual theme (`"light"` or `"dark"`) |
+| `Tooltip` | String | `""` | Custom tooltip text for the input field (programmatic access only) |
+| `TabIndex` | String | `"0"` | Tab order index for keyboard navigation (programmatic access only) |
+| `AccessibilityText` | String | `""` | Accessibility text for screen readers (programmatic access only) |
+| `ControlStyle` | String | `""` | Control style template (programmatic access only) |
+| `Enabled` | String | `"true"` | Legacy property for enabled state (programmatic access only, use `IsEnabled` instead) |
+| `ReadOnly` | String | `"false"` | Legacy property for read-only state (programmatic access only, use `IsReadOnly` instead) |
+| `Format` | String | `""` | Format property (programmatic access only) |
 
 ### Standard K2 Control Properties
 
@@ -55,6 +62,7 @@ A customizable CAPTCHA box for Control Dojo that provides bot protection using o
 | `OnEnter` | Fired when the user presses Enter in the input field |
 | `Verified` | Fired when CAPTCHA verification is successful |
 | `VerificationFailed` | Fired when CAPTCHA verification fails |
+| `Rendered` | Fired when the control finishes initial rendering |
 
 ## Methods
 

Controls/CAPTCHA Box/manifest.json

@@ -19,6 +19,7 @@
   "displayName": "CAPTCHA Box",
   "tagName": "captcha-control",
   "valuePropertyID": "CaptchaResponse",
+  "datatypes": ["Text"],
   "supports": [
     "Value",
     "Width",