=== Kashida Color Library ===
Contributors: mrwanbg
Tags: colors, color palette, color swatches, color picker, shortcode
Requires at least: 5.8
Tested up to: 7.1
Requires PHP: 8.0
Stable tag: 2.6.11
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Create responsive color collections with custom attributes, search, similar colors, and CSV, XLSX, or ZIP import.

== Description ==

Kashida Color Library is a lightweight WordPress plugin for creating, managing, and displaying reusable color collections.

Use it for paint, fabrics, interior materials, plastics, wood, ceramics, printing, automotive, cosmetics, product catalogs, and any business that needs a dedicated color guide.

= Color Groups and Collections =
* Create reusable color groups with a stable group code, description, featured image, and custom attribute.
* Add color names, commercial codes, HEX values, and sample images.
* Use a custom attribute such as Surface, Material, Texture, Finish, or any label suitable for your industry.
* Display published groups using the Collection Listing shortcode.

= Flexible Display Styles =
Choose Rectangle, Square, Circle, or Compact layouts for color cards and collections. Configure Desktop, Tablet, and Mobile columns independently.

= Color Information and Tools =
* Display color names, codes, HEX, RGB, HSL, attributes, and sample images.
* Search by color name, code, HEX, RGB, HSL, or attribute.
* Filter by the configured group attribute and sort by name, code, attribute, or HEX.
* Use the color wheel to find nearby colors.
* Select, copy, print, and share color information.

= Import and Export =
* Import colors from CSV, XLSX, or ZIP files.
* Preview imports and choose how duplicate codes are handled.
* Export color group data as CSV or XLSX.
* ZIP imports can include supported sample images matched by color name or code.
* Import validation checks file types, sizes, data rows, image files, and unsafe ZIP paths.

= Shortcode Generator =
Generate responsive shortcodes without writing code. Choose one or more color groups, set the layout and responsive columns, and control which fields and tools are displayed.

= Main Shortcodes =
Display one group:

`[kashida_colors_showcase group="KCS-0001"]`

Display published color collections:

`[kashida_collections]`

Customize collection columns and shape:

`[kashida_collections desktop="5" tablet="3" mobile="2" shape="square"]`

Display multiple groups:

`[kashida_colors_showcase groups="KCS-0001,KCS-0002" desktop="6" tablet="4" mobile="2"]`

Hide search, filters, and sorting:

`[kashida_colors_showcase group="KCS-0001" search="false" filter="false" sort="false"]`

Control visible color information:

`[kashida_colors_showcase group="KCS-0001" show_code="false" show_hex="true" show_rgb="true" show_hsl="true"]`

The legacy `[paint_colors]` shortcode may remain available in existing installations, but `[kashida_colors_showcase]` is the recommended namespaced shortcode.

= Lightweight and Translation Ready =
The core plugin does not require an external API or third-party service. It uses WordPress data storage and is prepared for translation with gettext and multilingual plugins such as Polylang.

== الوصف باللغة العربية ==

مكتبة كشيدة للألوان إضافة خفيفة لووردبريس لإنشاء مجموعات الألوان وإدارتها وعرضها بطريقة منظمة ومتجاوبة.

يمكن استخدامها للدهانات والأقمشة والديكور والبلاستيك والخشب والسيراميك والطباعة والسيارات ومستحضرات التجميل، وأي مجال يحتاج إلى دليل ألوان خاص به.

= المميزات الرئيسية =
* إنشاء مجموعات ألوان مع رمز ثابت ووصف وصورة مميزة.
* إضافة اسم اللون ورمزه التجاري وقيم HEX وRGB وHSL وصورة عينة.
* تحديد سمة مخصصة لكل مجموعة، مثل الخامة أو الملمس أو السطح أو التشطيب.
* أربعة أنماط عرض: مستطيل ومربع ودائرة ومضغوط.
* تحديد عدد الأعمدة بشكل مستقل لأجهزة سطح المكتب والأجهزة اللوحية والهواتف.
* البحث والتصفية والترتيب حسب الاسم والرمز وقيم اللون والسمة.
* اكتشاف الألوان القريبة باستخدام عجلة الألوان.
* تحديد الألوان ونسخ معلوماتها وطباعتها ومشاركتها.
* استيراد CSV وXLSX وZIP مع معاينة البيانات ومعالجة التكرارات.
* تصدير بيانات المجموعات إلى CSV أو XLSX.
* منشئ رموز مختصرة لتخصيص العرض دون كتابة كود.
* جاهزية الترجمة باستخدام ملفات gettext ودعم إضافات متعددة اللغات مثل Polylang.

= أمثلة الرموز المختصرة =
عرض مجموعة ألوان:

`[kashida_colors_showcase group="KCS-0001"]`

عرض المجموعات المنشورة:

`[kashida_collections]`

تخصيص الأعمدة والشكل:

`[kashida_collections desktop="5" tablet="3" mobile="2" shape="square"]`

عرض عدة مجموعات:

`[kashida_colors_showcase groups="KCS-0001,KCS-0002" desktop="6" tablet="4" mobile="2"]`

= التثبيت والاستخدام =
1. ثبّت الإضافة وفعّلها من صفحة الإضافات في ووردبريس.
2. افتح **Color Groups** ثم اختر **Add Group** لإنشاء مجموعة.
3. أضف الألوان يدويًا أو استوردها من ملف CSV أو XLSX أو ZIP.
4. اضبط السمة والحقول التي تريد عرضها.
5. استخدم **Shortcode Generator** لإنشاء الرمز المختصر.
6. انسخ الرمز المختصر إلى صفحة أو تدوينة واحفظها.

= متطلبات التشغيل =
* WordPress 5.8 أو أحدث.
* PHP 8.0 أو أحدث.

== Installation ==

1. Install the plugin ZIP through Plugins → Add New → Upload Plugin, or upload the plugin folder to `/wp-content/plugins/`.
2. Activate Kashida Color Library.
3. Open Color Groups → Add Group.
4. Create a group and add colors manually or import a CSV, XLSX, or ZIP file.
5. Configure the group attribute and display options.
6. Use the Shortcode Generator and paste the generated shortcode into a page or post.

== Frequently Asked Questions ==

= Does the plugin require an external API? =
No. The core color management and display features work within WordPress and do not require an external API.

= Can I use it for products other than paint? =
Yes. It is a general-purpose color guide for fabrics, materials, product catalogs, and any industry that uses color collections.

= Which import formats are supported? =
CSV, XLSX, and ZIP. ZIP files can contain a CSV or XLSX data file and supported sample images.

= Can I display multiple groups together? =
Yes. Use the `groups` attribute with comma-separated group codes.

= Are draft groups publicly visible? =
No. Public shortcodes and Collection Listing include published groups only.

= Can I translate the plugin? =
Yes. The interface is translation-ready. This release includes an Arabic translation catalog in the `languages` directory when the PO/MO files are installed with the plugin.

== Changelog ==

= 2.6.11 =
* Corrected translation documentation and clarified the primary shortcode.

= 2.6.8 =
* Updated the WordPress admin menu label to Kashida Color Library.

= 2.6.7 =
* Updated plugin naming for directory compatibility.
* Retained improved circular-card hover controls.

= 2.6.6 =
* Improved circular color-card action buttons for desktop, keyboard, and touch devices.

= 2.6.4 =
* Fixed the single Color Group template and template variable warnings.
* Improved accessibility of circular swatch actions.

= 2.6.3 =
* Fixed circular swatch action buttons.
* Replaced direct database migration queries with WordPress APIs.
* Added a translators comment and improved the POT catalog.

= 2.6.0 =
* Prepared the plugin for WordPress.org release review.
* Hardened public shortcode output and reviewed import, export, permission, nonce, sanitization, escaping, and ZIP security handling.

== Source Code ==

https://github.com/mrwan-bg/kashida-color-library
