chore: refactor project structure and developer tooling

.github/workflows/release.yml

@@ -0,0 +1,45 @@
+name: Release Plugin
+
+on:
+  push:
+    branches:
+      - production
+
+jobs:
+  build-and-release:
+    name: Build and Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # Required to create releases and tags
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+          tools: composer
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Get Version
+        id: get_version
+        run: echo "VERSION=$(jq -r .version package.json)" >> $GITHUB_OUTPUT
+
+      - name: Build Plugin ZIP
+        run: make zip
+
+      - name: Create Release and Upload Asset
+        uses: softprops/action-gh-release@v1
+        with:
+          tag_name: v${{ steps.get_version.outputs.VERSION }}
+          name: v${{ steps.get_version.outputs.VERSION }}
+          generate_release_notes: true
+          files: core-carousel.zip
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -28,7 +28,6 @@ phpstan.neon
 # IDE files
 .vscode/
 .idea/
-.github/
 *.iml
 *.sublime-project
 *.sublime-workspace
@@ -37,3 +36,4 @@ phpstan.neon
 # Build
 build/
 tsconfig.tsbuildinfo
+core-carousel.zip

.husky/commit-msg

@@ -0,0 +1 @@
+npx --no -- commitlint --edit $1

.husky/pre-commit

@@ -0,0 +1 @@
+npm run lint:js

CHANGELOG.md

@@ -0,0 +1,17 @@
+# 1.0.0 (2026-02-03)
+
+
+### Bug Fixes
+
+* Gap issue fixed for the carousel items ([5277b89](https://github.com/rtCamp/carousel-system-interactivity-api/commit/5277b89545c973f13c22f6d1d7cf21e19958305f))
+
+
+### Features
+
+* Add example carousels for hero, logo showcase, and testimonials ([d2b6e4a](https://github.com/rtCamp/carousel-system-interactivity-api/commit/d2b6e4ae0f915f6edfb6ddf637c4a88878375e4b))
+* Add slide to scroll option ([f2adab3](https://github.com/rtCamp/carousel-system-interactivity-api/commit/f2adab310015347400a1c2e6437b3a68566a6c9d))
+* Enhance vertical axis support and adjust slide dimensions in carousel styles ([2ec3e40](https://github.com/rtCamp/carousel-system-interactivity-api/commit/2ec3e40e8e34655d3417b25e16feaee41451c604))
+* Refactor context handling and define global window interface for carousel context ([5aab80e](https://github.com/rtCamp/carousel-system-interactivity-api/commit/5aab80edd103ee66d8e212359eb0f8d2ad01acb7))
+
+
+

DEVELOPMENT.md

@@ -0,0 +1,75 @@
+# Development Reference
+
+This project uses **npm**, **Composer**, and **Make** for development and build workflows.
+
+## Quick Start
+
+```bash
+# Fast setup for development (installs dependencies & builds)
+make dev
+
+# Start development server (watches for changes)
+npm start
+```
+
+## Available Commands
+
+### Build & Watch
+
+| Command | Description |
+| :--- | :--- |
+| `npm start` | Starts the build in watch mode. |
+| `make dev` | **Development Build.** Fast, incremental install (`npm install`) + build. |
+| `make build` | **Production Build.** Clean install (`npm ci`) + build. Slow but safe. |
+
+### Quality Control (Linting & Testing)
+
+| Command | Description |
+| :--- | :--- |
+| `npm run lint:js` | Lints JavaScript and TypeScript files. |
+| `npm run lint:js:fix` | Fixes JS/TS linting errors. |
+| `npm run lint:css` | Lints SCSS files. |
+| `npm run lint:css:fix` | Fixes SCSS linting errors. |
+| `composer run lint` | Lints PHP files (PHPCS). |
+| `composer run format` | Fixes PHP linting errors (PHPCBF). |
+| `composer run phpstan` | Runs static analysis with PHPStan. |
+
+### Distribution
+
+| Command | Description |
+| :--- | :--- |
+| `make zip` | **Production Build.** Runs a clean install (`npm ci`) and creates the ZIP. |
+| `make quick-zip` | **Development Package.** Uses existing `node_modules` (incremental) for faster zipping. |
+| `make clean` | Removes build artifacts (`build/`, `vendor/`, `node_modules/`, `.zip`). |
+
+### Versioning & Changelog
+
+| Command | Description |
+| :--- | :--- |
+| `npm run changelog` | Generates/Updates `CHANGELOG.md` based on commits. |
+| `npm run version` | Internal hook used by `npm version` to update changelog and stage it. |
+| `npm version [major|minor|patch]` | Bumps version in `package.json`, updates `CHANGELOG.md`, and creates a git tag. |
+
+## Local GitHub Actions (act)
+
+To test the release workflow locally, we use [act](https://github.com/nektos/act).
+
+### Prerequisites
+- [Docker](https://www.docker.com/products/docker-desktop/) installed and running.
+- `act` installed: `brew install act` (macOS).
+
+### Usage
+```bash
+# Run the release workflow locally
+make act
+# OR
+npm run test:actions
+```
+
+## Directory Structure
+
+- `src/` - Source code for blocks (React/TypeScript/SCSS).
+- `inc/` - PHP classes and traits (PSR-4 `Core_Carousel`).
+- `build/` - Compiled assets (generated by `npm run build`).
+- `docs/` - Documentation files.
+- `examples/` - Block patterns and examples.

Makefile

@@ -0,0 +1,85 @@
+# Configuration
+PLUGIN_SLUG := core-carousel
+PLUGIN_VERSION := 1.0.0
+BUILD_DIR := build-dist
+ZIP_NAME := $(PLUGIN_SLUG).zip
+
+# Default target
+.PHONY: all
+all: build zip
+
+# Production Build (Slow, Clean)
+# Uses 'npm ci' to wipe node_modules and ensure exact versions.
+.PHONY: build
+build:
+	@echo "Installing Composer dependencies (Production)..."
+	@composer install --no-dev --optimize-autoloader
+	@echo "Installing NPM dependencies (Clean)..."
+	@npm ci
+	@echo "Building assets..."
+	@npm run build
+
+# Development Build (Fast, Incremental)
+# Uses 'npm install' to respect existing node_modules.
+.PHONY: dev
+dev:
+	@echo "Installing Composer dependencies..."
+	@composer install
+	@echo "Installing NPM dependencies (Incremental)..."
+	@npm install
+	@echo "Building assets..."
+	@npm run build
+
+# Production Build & Zip (Slow, for Releases)
+.PHONY: zip
+zip: build dist
+
+# Development Build & Zip (Fast, for Testing)
+.PHONY: quick-zip
+quick-zip: dev dist
+
+# Internal target for creating the distribution package
+.PHONY: dist
+dist:
+	@echo "Creating distribution package..."
+	@rm -rf $(BUILD_DIR)
+	@mkdir -p $(BUILD_DIR)/$(PLUGIN_SLUG)
+
+	@# Copy Files
+	@rsync -r \
+		--exclude='.*' \
+		--exclude='node_modules' \
+		--exclude='tests' \
+		--exclude='phpunit.xml.dist' \
+		--exclude='phpcs.xml.dist' \
+		--exclude='webpack.config.js' \
+		--exclude='package.json' \
+		--exclude='package-lock.json' \
+		--exclude='tsconfig.json' \
+		--exclude='composer.json' \
+		--exclude='composer.lock' \
+		--exclude='Makefile' \
+		--exclude='README.md' \
+		--exclude='CHANGELOG.md' \
+		--exclude='$(BUILD_DIR)' \
+		--exclude='*.zip' \
+		./ $(BUILD_DIR)/$(PLUGIN_SLUG)/
+
+	@echo "Zipping..."
+	@cd $(BUILD_DIR) && zip -r ../$(ZIP_NAME) $(PLUGIN_SLUG)
+	@echo "Done! Plugin zip created at $(ZIP_NAME)"
+	@rm -rf $(BUILD_DIR)
+
+# Clean up
+.PHONY: clean
+clean:
+	@rm -f $(ZIP_NAME)
+	@rm -rf $(BUILD_DIR)
+	@rm -rf build
+	@rm -rf node_modules
+	@rm -rf vendor
+
+# Local GitHub Actions simulation
+.PHONY: act
+act:
+	@act -W .github/workflows/release.yml