diff --git a/.github/ISSUE_TEMPLATE/01-bug-report.md b/.github/ISSUE_TEMPLATE/01-bug-report.md index 223c82df9..b7463879f 100644 --- a/.github/ISSUE_TEMPLATE/01-bug-report.md +++ b/.github/ISSUE_TEMPLATE/01-bug-report.md @@ -17,6 +17,30 @@ A clear and concise description of what the bug is. ## To Reproduce + author: "LightSpeedWP Team" + contributors: + - name: "Ash" + github: "ash" + - name: "LightSpeedWP" + github: "lightspeedwp" + date: "2025-09-17" + last_modified: "2025-09-17" + tags: + - bug + - wordpress + - report + - issue + - triage + categories: + - issue + - bug + - report + version: "1.0.0" + permalink: "/issue-template/bug-report" + license: "MIT" + related_links: + - "https://github.com/lightspeedwp/.github" + - "https://developer.wordpress.org/coding-standards/" Steps to reproduce the behavior: 1. Go to '...' diff --git a/.github/ISSUE_TEMPLATE/02-enhancement.md b/.github/ISSUE_TEMPLATE/02-enhancement.md index ea984523f..e464acfd4 100644 --- a/.github/ISSUE_TEMPLATE/02-enhancement.md +++ b/.github/ISSUE_TEMPLATE/02-enhancement.md @@ -17,6 +17,30 @@ A clear and concise description of the problem or opportunity you are trying to ## Describe the solution you'd like + author: "LightSpeedWP Team" + contributors: + - name: "Ash" + github: "ash" + - name: "LightSpeedWP" + github: "lightspeedwp" + date: "2025-09-17" + last_modified: "2025-09-17" + tags: + - enhancement + - feature + - wordpress + - request + - triage + categories: + - issue + - enhancement + - feature + version: "1.0.0" + permalink: "/issue-template/enhancement-request" + license: "MIT" + related_links: + - "https://github.com/lightspeedwp/.github" + - "https://developer.wordpress.org/coding-standards/" A clear and concise description of what you want to happen. If possible, provide examples or references to similar features in other plugins/themes. ## Designs / Mockups diff --git a/.github/ISSUE_TEMPLATE/03-help.md b/.github/ISSUE_TEMPLATE/03-help.md index 448b027ee..70dbb3030 100644 --- a/.github/ISSUE_TEMPLATE/03-help.md +++ b/.github/ISSUE_TEMPLATE/03-help.md @@ -17,6 +17,28 @@ Please provide as much detail as possible to help us assist you efficiently. ## Question Summary + author: "LightSpeedWP Team" + contributors: + - name: "Ash" + github: "ash" + - name: "LightSpeedWP" + github: "lightspeedwp" + date: "2025-09-17" + last_modified: "2025-09-17" + tags: + - help + - support + - question + - wordpress + categories: + - issue + - support + - question + version: "1.0.0" + permalink: "/issue-template/help" + license: "MIT" + related_links: + - "https://github.com/lightspeedwp/.github" diff --git a/.github/ISSUE_TEMPLATE/04-feature-request.md b/.github/ISSUE_TEMPLATE/04-feature-request.md index f9ae98c54..c4c0c6bcd 100644 --- a/.github/ISSUE_TEMPLATE/04-feature-request.md +++ b/.github/ISSUE_TEMPLATE/04-feature-request.md @@ -17,6 +17,27 @@ A clear and concise description of the problem or opportunity you are trying to ## Describe the feature you'd like + author: "LightSpeedWP Team" + contributors: + - name: "Ash" + github: "ash" + - name: "LightSpeedWP" + github: "lightspeedwp" + date: "2025-09-17" + last_modified: "2025-09-17" + tags: + - feature + - request + - wordpress + - triage + categories: + - issue + - feature + version: "1.0.0" + permalink: "/issue-template/feature-request" + license: "MIT" + related_links: + - "https://github.com/lightspeedwp/.github" A clear and concise description of what you want to happen. If possible, provide examples or references to similar features in other plugins/themes. ## Designs / Mockups diff --git a/.github/ISSUE_TEMPLATE/05-code-refactoring.md b/.github/ISSUE_TEMPLATE/05-code-refactoring.md index b33235f05..6019fddcf 100644 --- a/.github/ISSUE_TEMPLATE/05-code-refactoring.md +++ b/.github/ISSUE_TEMPLATE/05-code-refactoring.md @@ -17,6 +17,28 @@ type: 'refactor' - [ ] Admin interface - [ ] Integrations - [ ] Other: + author: "LightSpeedWP Team" + contributors: + - name: "Ash" + github: "ash" + - name: "LightSpeedWP" + github: "lightspeedwp" + date: "2025-09-17" + last_modified: "2025-09-17" + tags: + - refactor + - code quality + - review + - wordpress + categories: + - issue + - refactor + - review + version: "1.0.0" + permalink: "/issue-template/code-refactoring" + license: "MIT" + related_links: + - "https://github.com/lightspeedwp/.github" ## Is your code refactoring request related to a problem? diff --git a/.github/instructions/coding-standards.instructions.md b/.github/instructions/coding-standards.instructions.md index 64ec1ba21..d27e276f9 100644 --- a/.github/instructions/coding-standards.instructions.md +++ b/.github/instructions/coding-standards.instructions.md @@ -7,6 +7,17 @@ contributors: github: "ashleyshaw" - name: "LightSpeedWP" github: "lightspeedwp" +version: "1.0.0" + - wordpress + - coding-standards + - php + - javascript + - css + - best-practices + - "https://github.com/lightspeedwp/.github" + - documentation + - instructions + - guides tags: - wordpress - coding-standards @@ -27,11 +38,11 @@ mode: "agent" # Coding Standards Instructions -These guidelines apply to all WordPress projects maintained by LightSpeed. - -## PHP -- Follow [WordPress PHP Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/) -- Use 4 spaces for indentation, no tabs + related_links: + - "https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/" + - "https://developer.wordpress.org/coding-standards/wordpress-coding-standards/javascript/" + - "https://developer.wordpress.org/coding-standards/wordpress-coding-standards/css/" + - "https://github.com/lightspeedwp/.github" - Escape and sanitize all dynamic output - Use meaningful, descriptive function and variable names - Add inline documentation using phpdoc diff --git a/.github/instructions/html-template.instructions.md b/.github/instructions/html-template.instructions.md index 3189dd74c..874a8e42c 100644 --- a/.github/instructions/html-template.instructions.md +++ b/.github/instructions/html-template.instructions.md @@ -9,6 +9,9 @@ contributors: github: "ashleyshaw" - name: "LightSpeedWP" github: "lightspeedwp" +version: "1.0.0" +permalink: "/instructions/html-template" +license: "MIT" tags: - html - template @@ -25,17 +28,16 @@ permalink: "/instructions/html-template" license: "MIT" type: "instructions" mode: "agent" -applyTo: "**/*.html" --- # HTML Template Instructions ## Block Template Structure - -- Use semantic HTML elements (header, main, footer, section, article). -- Maintain proper nesting and hierarchy of block elements. -- Follow progressive enhancement principles for markup. -- Keep templates modular and reusable where possible. + related_links: + - "https://developer.wordpress.org/themes/block-themes/templates/" + - "https://developer.wordpress.org/themes/block-themes/template-parts/" + - "https://developer.wordpress.org/block-editor/reference-guides/template-structure/" + - "https://github.com/lightspeedwp/.github" - Test templates with both light and dark color schemes. ## Template Parts diff --git a/.github/instructions/pattern-development.instructions.md b/.github/instructions/pattern-development.instructions.md index 7c8e6dabf..82d6e2806 100644 --- a/.github/instructions/pattern-development.instructions.md +++ b/.github/instructions/pattern-development.instructions.md @@ -9,6 +9,8 @@ contributors: github: "ashleyshaw" - name: "LightSpeedWP" github: "lightspeedwp" +version: "1.0.0" +permalink: "/instructions/pattern-development" tags: - pattern - wordpress @@ -31,10 +33,10 @@ applyTo: "**/patterns/**/*.php" # Block Pattern Development Instructions ## Pattern Structure - -- Use descriptive comments to document each section of the pattern. -- Follow a logical structure with clear parent-child relationships. -- Group related blocks using the Group block where appropriate. + related_links: + - "https://developer.wordpress.org/themes/patterns/" + - "https://developer.wordpress.org/themes/patterns/starter-patterns/" + - "https://developer.wordpress.org/themes/patterns/usage-in-templates/" - Use appropriate block variations based on content needs. - Test pattern across different viewport sizes. diff --git a/.github/instructions/php-block.instructions.md b/.github/instructions/php-block.instructions.md index 25a4256b3..446785136 100644 --- a/.github/instructions/php-block.instructions.md +++ b/.github/instructions/php-block.instructions.md @@ -30,6 +30,20 @@ categories: - instructions - guides applyTo: "**/*.php" +excludePaths: ["vendor/**", "node_modules/**"] +version: "1.0.0" +author: "LightSpeed Team" +priority: "high" +createdAt: "2025-01-01" +updatedAt: "2023-06-15" +relatedLinks: + - description: "WordPress Coding Standards" + url: "https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/" + - description: "Block Pattern Documentation" + url: "https://developer.wordpress.org/block-editor/reference-guides/block-api/block-patterns/" +examples: + - "patterns/cta/newsletter.php" + - "inc/blocks/register-patterns.php" --- # PHP Block & Theme Setup Instructions diff --git a/.github/instructions/playwright-tests.instructions.md b/.github/instructions/playwright-tests.instructions.md new file mode 100644 index 000000000..1d03fc0d0 --- /dev/null +++ b/.github/instructions/playwright-tests.instructions.md @@ -0,0 +1,169 @@ +--- +title: "Playwright Copilot Space Instructions" +description: "Comprehensive guide for Playwright browser automation, test generation, debugging, and best practices for LightSpeed projects." +author: "LightSpeedWP Team" +contributors: + - name: "Ash Shaw" + github: "ashleyshaw" + - name: "LightSpeedWP" + github: "lightspeedwp" +date: "2025-09-17" +last_modified: "2025-09-17" +tags: + - playwright + - testing + - automation + - browser + - MCP + - CI/CD + - best-practices +categories: + - documentation + - instructions + - guides +version: "1.0.0" +permalink: "/instructions/playwright-tests" +license: "MIT" +related_links: + - "https://playwright.dev/docs/intro" + - "https://github.com/lightspeedwp/.github" + - "https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright" +type: "instructions" +mode: "agent" +--- + + +# Playwright Test Instructions + +These guidelines outline best practices for writing, organizing, and maintaining Playwright tests for LightSpeed projects, with a focus on WordPress themes, blocks, and custom patterns. + +--- + +## Directory & Setup + +- Place Playwright tests in a dedicated directory, e.g. `/tests/playwright/` within your project. +- Install Playwright and its dependencies: + ```bash + npm install --save-dev @playwright/test + npx playwright install + ``` +- Install WordPress-specific E2E helpers: + ```bash + npm install --save-dev @wordpress/e2e-test-utils-playwright + ``` + Reference: [WordPress E2E Test Utils](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-e2e-test-utils-playwright/) + +--- + +## Writing Tests + +- Create test files with `.spec.ts` or `.spec.js` extensions. +- Use descriptive test and file names reflecting the feature, pattern, or block under test. +- Example: + ```js + import { test, expect } from '@playwright/test'; + + test.describe('Homepage', () => { + test('should load and display main banner', async ({ page }) => { + await page.goto('https://your-site.test'); + await expect(page.locator('.main-banner')).toBeVisible(); + }); + }); + ``` +- For WordPress block/editor tests, use E2E Test Utils for common editor actions. + +--- + +## Best Practices + +- **Isolation:** Each test should run independently, with its own setup and teardown. +- **Selectors:** Use robust selectors (`data-*` attributes or ARIA labels) instead of CSS classes. +- **Assertions:** Assert only what matters for the scenario; avoid over-asserting. +- **Test Speed:** Avoid unnecessary waits; use Playwright's automatic waiting for elements. +- **Coverage:** Focus on critical user paths, accessibility, and edge cases. +- **Maintainability:** Refactor repeated code into helpers or fixtures. + +See: [Playwright Best Practices](https://playwright.dev/docs/best-practices) + +--- + +## MCP Agents for Test Generation + +Leverage [Playwright MCP Agents](https://playwright.dev/agents/playwright-mcp-generating-tests) to automate test generation, especially for UI regression and repeated workflows. + +--- + +## WordPress Theme Testing + +Reference [WordPress Theme Testing Guides](https://developer.wordpress.org/themes/advanced-topics/theme-testing/) for comprehensive checklists. + +Ensure tests cover: + +- Block registration and rendering. +- Theme customizer options. +- Frontend and backend appearance. +- Accessibility and device compatibility. + +More resources: +- [Theme Testing](https://developer.wordpress.org/themes/releasing-your-theme/testing/) +- [Build Process Integration](https://developer.wordpress.org/themes/advanced-topics/build-process/) + +--- + +## Organizing Tests + +- Group related tests by feature, block, or template. +- Use Playwright’s `test.describe()` to structure suites. +- Use fixtures for setup tasks (login, DB resets, etc.). + +--- + +## Running Tests + +- Run all tests: + ```bash + npx playwright test + ``` +- Run a specific test: + ```bash + npx playwright test path/to/test.spec.ts + ``` +- Generate HTML reports: + ```bash + npx playwright test --reporter=html + ``` + +--- + +## CI Integration + +- Integrate Playwright into your CI/CD pipeline (e.g., GitHub Actions). +- Ensure your workflow installs dependencies and runs tests on pull requests and merges. +- Reference: [Playwright CI Docs](https://playwright.dev/docs/ci-intro) + +--- + +## Resources + +- [Playwright Documentation](https://playwright.dev/docs/intro) +- [Agents & Automation](https://playwright.dev/agents) +- [Best Practices](https://playwright.dev/docs/best-practices) +- [WordPress Theme Testing](https://developer.wordpress.org/themes/advanced-topics/theme-testing/) +- [Block Editor E2E Utils](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-e2e-test-utils-playwright/) + +--- + +## Contribution + +- Follow [LightSpeed Coding Standards](./coding-standards.instructions.md). +- Submit Playwright tests as part of feature pull requests. +- Review tests for reliability, clarity, and coverage. +- For questions or suggestions, open an issue or discuss with the team. + +--- + +**Maximum for this folder:** +- This file is located in: `@lightspeedwp/.github/files/.github/instructions` +- All instructions files in this folder must follow [LightSpeed organizational guidelines](https://github.com/lightspeedwp/.github/blob/master/.github/custom-instructions.md). + +--- \ No newline at end of file diff --git a/examples/IMPLEMENTATION.md b/examples/IMPLEMENTATION.md new file mode 100644 index 000000000..d5ba0d8bf --- /dev/null +++ b/examples/IMPLEMENTATION.md @@ -0,0 +1,123 @@ +# WordPress Block Structure Implementation + +This implementation demonstrates the typical file structure for WordPress blocks based on the [WordPress Block Editor documentation](https://developer.wordpress.org/block-editor/getting-started/fundamentals/file-structure-of-a-block/) and follows LightSpeed coding standards. + +## What Has Been Implemented + +### ✅ Complete Block Structure +Following the WordPress documentation, this implementation includes all essential files for a modern WordPress block: + +1. **`block.json`** - Block metadata and configuration (API version 3) +2. **`src/index.js`** - Main block registration entry point +3. **`src/edit.js`** - Editor interface with React components +4. **`src/save.js`** - Frontend save function +5. **`src/editor.scss`** - Editor-specific styles +6. **`src/style.scss`** - Frontend and editor styles +7. **`example-block.php`** - PHP registration and server-side functionality +8. **`package.json`** - Build configuration and dependencies + +### ✅ LightSpeed Standards Compliance +- **WordPress Coding Standards**: PHP follows WordPress guidelines +- **4-space indentation**: Consistent throughout all files +- **Security**: Proper escaping and sanitization +- **Internationalization**: Correct text domain and translation functions +- **Theme.json integration**: Uses design tokens for styling +- **Performance optimization**: Minimal dependencies and efficient code + +### ✅ Block Patterns +Two example patterns demonstrating LightSpeed pattern development: +- **Hero CTA**: Complex responsive hero section +- **Simple CTA**: Basic call-to-action pattern + +Both patterns follow the pattern development guidelines with proper headers, categories, and theme.json integration. + +## Key Features + +### Modern WordPress Block API +- Uses API version 3 (latest) +- Block.json configuration approach +- React component architecture +- SCSS preprocessing +- Webpack build process + +### Accessibility & Performance +- ARIA labels and semantic markup +- Keyboard navigation support +- High contrast mode compatibility +- Reduced motion preferences +- Mobile-first responsive design +- Optimized asset loading + +### Developer Experience +- Hot reloading with `npm start` +- Linting and formatting tools +- Clear documentation +- Consistent code organization +- Build optimization + +## File Organization + +``` +examples/ +├── README.md # Complete documentation +├── example-block/ # Main block directory +│ ├── .gitignore # Ignore build files +│ ├── block.json # Block configuration +│ ├── example-block.php # PHP registration +│ ├── package.json # Dependencies & scripts +│ ├── webpack.config.js # Build configuration +│ └── src/ # Source files +│ ├── index.js # Block registration +│ ├── edit.js # Editor component +│ ├── save.js # Save component +│ ├── editor.scss # Editor styles +│ └── style.scss # Frontend styles +└── patterns/ # Block patterns + ├── hero-cta.php # Complex hero pattern + └── simple-cta.php # Simple CTA pattern +``` + +## Usage Instructions + +### 1. Development Setup +```bash +cd examples/example-block +npm install +npm run start # Development mode with hot reloading +``` + +### 2. Production Build +```bash +npm run build # Creates optimized build files +``` + +### 3. Integration +Include in your theme's `functions.php`: +```php +require_once get_template_directory() . '/examples/example-block/example-block.php'; +``` + +## Standards Followed + +### WordPress Documentation +- [File Structure of a Block](https://developer.wordpress.org/block-editor/getting-started/fundamentals/file-structure-of-a-block/) +- [Block API Reference](https://developer.wordpress.org/block-editor/reference-guides/block-api/) +- [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/) + +### LightSpeed Guidelines +- [PHP Block Instructions](../.github/instructions/php-block.instructions.md) +- [Pattern Development Instructions](../.github/instructions/pattern-development.instructions.md) +- [Coding Standards](../.github/instructions/coding-standards.instructions.md) + +## Next Steps + +This implementation serves as a template for creating WordPress blocks in LightSpeed projects. Developers can: + +1. Copy this structure for new blocks +2. Modify the configuration in `block.json` +3. Customize the React components in `edit.js` and `save.js` +4. Add custom styling in the SCSS files +5. Extend PHP functionality as needed +6. Create additional patterns following the examples + +The structure is designed to be scalable and maintainable while following WordPress and LightSpeed best practices. \ No newline at end of file diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 000000000..f3111a08d --- /dev/null +++ b/examples/README.md @@ -0,0 +1,189 @@ +# WordPress Block Structure Examples + +This directory demonstrates the typical file structure for WordPress blocks following the [WordPress documentation](https://developer.wordpress.org/block-editor/getting-started/fundamentals/file-structure-of-a-block/) and LightSpeed coding standards. + +## Directory Structure + +``` +examples/ +├── example-block/ # Main block directory +│ ├── src/ # Source files +│ │ ├── index.js # Main block registration +│ │ ├── edit.js # Editor interface component +│ │ ├── save.js # Frontend save component +│ │ ├── editor.scss # Editor-only styles +│ │ └── style.scss # Frontend and editor styles +│ ├── block.json # Block configuration +│ ├── example-block.php # PHP registration and server-side logic +│ └── package.json # Build configuration +└── patterns/ # Block patterns directory + ├── hero-cta.php # Hero section pattern + └── simple-cta.php # Simple CTA pattern +``` + +## File Descriptions + +### Core Block Files + +- **`block.json`** - The block configuration file containing metadata, attributes, and settings +- **`src/index.js`** - Main entry point that registers the block +- **`src/edit.js`** - React component for the block editor interface +- **`src/save.js`** - React component that defines the frontend output +- **`src/editor.scss`** - Styles that only apply in the editor +- **`src/style.scss`** - Styles that apply both in editor and frontend +- **`example-block.php`** - PHP file for server-side registration and functionality + +### Pattern Files + +- **`patterns/hero-cta.php`** - Complex hero section with multiple elements +- **`patterns/simple-cta.php`** - Simple call-to-action pattern + +## Key Features Demonstrated + +### Block Structure +- ✅ **API Version 3** - Uses latest block API +- ✅ **Block.json Configuration** - Modern block registration +- ✅ **React Components** - Separate edit and save components +- ✅ **SCSS Preprocessing** - Organized stylesheets +- ✅ **Internationalization** - Proper translation support +- ✅ **Accessibility** - ARIA labels and keyboard navigation +- ✅ **Color Support** - Theme color integration +- ✅ **Typography Support** - Font size and line height controls +- ✅ **Spacing Support** - Padding and margin controls + +### LightSpeed Standards +- ✅ **WordPress Coding Standards** - PHP follows WordPress guidelines +- ✅ **4-space Indentation** - Consistent formatting +- ✅ **Proper Escaping** - Security best practices +- ✅ **Translation Ready** - Correct text domain usage +- ✅ **Theme.json Integration** - Uses theme design tokens +- ✅ **Performance Optimized** - Minimal dependencies + +### Pattern Features +- ✅ **Pattern Headers** - Proper metadata for discovery +- ✅ **Category Assignment** - Organized in logical groups +- ✅ **Responsive Design** - Mobile-first approach +- ✅ **Theme Integration** - Uses theme.json variables +- ✅ **Content Strategy** - Realistic placeholder content + +## Getting Started + +### 1. Set Up Build Process + +```bash +# Navigate to the block directory +cd examples/example-block + +# Install dependencies +npm install + +# Start development mode +npm run start + +# Build for production +npm run build +``` + +### 2. Register the Block + +Include the PHP file in your theme's `functions.php`: + +```php +// Include the block registration +require_once get_template_directory() . '/examples/example-block/example-block.php'; +``` + +### 3. Register Patterns + +Include pattern files in your theme: + +```php +// Register patterns +require_once get_template_directory() . '/examples/patterns/hero-cta.php'; +require_once get_template_directory() . '/examples/patterns/simple-cta.php'; +``` + +## Development Workflow + +### Building Assets + +- **Development mode**: `npm run start` - Watches for changes and rebuilds automatically +- **Production build**: `npm run build` - Creates optimized production files + +### Code Quality + +- **Lint JavaScript**: `npm run lint:js` +- **Lint CSS**: `npm run lint:css` +- **Format code**: `npm run format` + +### File Organization + +``` +build/ # Generated files (after npm run build) +├── index.js # Compiled JavaScript +├── index.asset.php # WordPress asset dependencies +├── editor.css # Compiled editor styles +└── style.css # Compiled frontend styles +``` + +## Integration with WordPress + +### Block Categories + +The example includes custom block category registration: +- Category slug: `lsx-blocks` +- Category title: "LSX Blocks" + +### Asset Management + +- Automatic dependency management via `index.asset.php` +- Proper enqueuing for editor and frontend +- Version management for cache busting +- Translation support via `wp_set_script_translations()` + +### Server-side Rendering + +The example shows both: +- **Client-side rendering** (default) - Saves HTML in post content +- **Server-side rendering** (optional) - Dynamic PHP-generated output + +## Best Practices Demonstrated + +### Accessibility +- Proper heading hierarchy +- ARIA labels and roles +- Keyboard navigation support +- High contrast mode support +- Reduced motion preferences + +### Performance +- Minimal dependencies +- Optimized asset loading +- Efficient CSS selectors +- Reduced motion support + +### Security +- Input sanitization +- Output escaping +- Nonce verification (where applicable) +- Capability checks + +### Internationalization +- Translatable strings +- Proper text domain usage +- Translation function usage +- Script translations setup + +## Further Reading + +- [WordPress Block Editor Handbook](https://developer.wordpress.org/block-editor/) +- [Block API Reference](https://developer.wordpress.org/block-editor/reference-guides/block-api/) +- [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/) +- [LightSpeed Coding Standards](./../.github/instructions/coding-standards.instructions.md) + +## Support + +For questions or issues: +- Review the [GitHub Copilot instructions](../.github/copilot-instructions.md) +- Check the [prompt files](../.github/prompts/) for guidance +- Open an issue in the repository \ No newline at end of file diff --git a/examples/example-block/.gitignore b/examples/example-block/.gitignore new file mode 100644 index 000000000..293ebb188 --- /dev/null +++ b/examples/example-block/.gitignore @@ -0,0 +1,38 @@ +# Dependencies +node_modules/ +npm-debug.log* +yarn-debug.log* +yarn-error.log* + +# Build output +build/ +dist/ + +# Editor directories and files +.vscode/ +.idea/ +*.swp +*.swo +*~ + +# OS generated files +.DS_Store +.DS_Store? +._* +.Spotlight-V100 +.Trashes +ehthumbs.db +Thumbs.db + +# WordPress specific +wp-config.php +wp-content/uploads/ +wp-content/cache/ +wp-content/backup-db/ +wp-content/advanced-cache.php +wp-content/wp-cache-config.php + +# Temporary files +*.tmp +*.temp +.cache/ \ No newline at end of file diff --git a/examples/example-block/block.json b/examples/example-block/block.json new file mode 100644 index 000000000..48538b848 --- /dev/null +++ b/examples/example-block/block.json @@ -0,0 +1,60 @@ +{ + "$schema": "https://schemas.wp.org/trunk/block.json", + "apiVersion": 3, + "name": "lsx/example-block", + "version": "1.0.0", + "title": "LSX Example Block", + "category": "lsx-blocks", + "icon": "smiley", + "description": "An example block demonstrating typical WordPress block structure for LightSpeed projects.", + "keywords": [ + "example", + "lsx", + "lightspeed" + ], + "supports": { + "html": false, + "color": { + "background": true, + "text": true, + "gradients": true + }, + "spacing": { + "padding": true, + "margin": true + }, + "typography": { + "fontSize": true, + "lineHeight": true + }, + "anchor": true + }, + "attributes": { + "content": { + "type": "string", + "source": "html", + "selector": "p", + "default": "Hello from LSX Example Block!" + }, + "alignment": { + "type": "string", + "default": "center" + }, + "backgroundColor": { + "type": "string" + }, + "textColor": { + "type": "string" + } + }, + "example": { + "attributes": { + "content": "This is an example of the LSX Example Block in action.", + "alignment": "center" + } + }, + "textdomain": "lsx-theme", + "editorScript": "file:./index.js", + "editorStyle": "file:./editor.css", + "style": "file:./style.css" +} \ No newline at end of file diff --git a/examples/example-block/example-block.php b/examples/example-block/example-block.php new file mode 100644 index 000000000..5d3512f41 --- /dev/null +++ b/examples/example-block/example-block.php @@ -0,0 +1,190 @@ + 'lsx-blocks', + 'title' => esc_html__( 'LSX Blocks', 'lsx-theme' ), + 'icon' => 'admin-customizer', + ), + ) + ); +} +add_filter( 'block_categories_all', 'lsx_register_block_category' ); + +/** + * Enqueue block assets for editor and frontend + * + * @since 1.0.0 + */ +function lsx_example_block_assets() { + // Only load in admin/editor. + if ( ! is_admin() ) { + return; + } + + // Get asset file for dependency and version management. + $asset_file = include __DIR__ . '/build/index.asset.php'; + + // Enqueue block editor script. + wp_enqueue_script( + 'lsx-example-block-editor', + plugins_url( 'build/index.js', __FILE__ ), + $asset_file['dependencies'], + $asset_file['version'], + true + ); + + // Enqueue editor styles. + wp_enqueue_style( + 'lsx-example-block-editor', + plugins_url( 'build/editor.css', __FILE__ ), + array( 'wp-edit-blocks' ), + $asset_file['version'] + ); + + // Localize script for translations. + wp_set_script_translations( + 'lsx-example-block-editor', + 'lsx-theme', + __DIR__ . '/languages' + ); +} +add_action( 'enqueue_block_editor_assets', 'lsx_example_block_assets' ); + +/** + * Enqueue frontend block styles + * + * @since 1.0.0 + */ +function lsx_example_block_frontend_assets() { + // Get asset file for version management. + $asset_file = include __DIR__ . '/build/index.asset.php'; + + // Enqueue frontend styles. + wp_enqueue_style( + 'lsx-example-block-style', + plugins_url( 'build/style.css', __FILE__ ), + array(), + $asset_file['version'] + ); +} +add_action( 'wp_enqueue_scripts', 'lsx_example_block_frontend_assets' ); + +/** + * Add custom attributes to block wrapper + * + * @param string $block_content The block content. + * @param array $block The full block, including name and attributes. + * @return string Modified block content. + * @since 1.0.0 + */ +function lsx_example_block_wrapper_attributes( $block_content, $block ) { + // Only apply to our block. + if ( 'lsx/example-block' !== $block['blockName'] ) { + return $block_content; + } + + // Add custom CSS classes or data attributes if needed. + $custom_attributes = ''; + + // Example: Add schema markup. + $custom_attributes .= ' itemscope itemtype="https://schema.org/CreativeWork"'; + + // Add attributes to the block wrapper. + $block_content = str_replace( + 'class="wp-block-lsx-example-block', + 'class="wp-block-lsx-example-block' . $custom_attributes . ' ', + $block_content + ); + + return $block_content; +} +add_filter( 'render_block', 'lsx_example_block_wrapper_attributes', 10, 2 ); + +/** + * Server-side rendering callback (if needed for dynamic blocks) + * + * @param array $attributes Block attributes. + * @return string Block output. + * @since 1.0.0 + */ +function lsx_example_block_render_callback( $attributes ) { + // Sanitize attributes. + $content = isset( $attributes['content'] ) ? wp_kses_post( $attributes['content'] ) : ''; + $alignment = isset( $attributes['alignment'] ) ? esc_attr( $attributes['alignment'] ) : 'center'; + $background_color = isset( $attributes['backgroundColor'] ) ? esc_attr( $attributes['backgroundColor'] ) : ''; + $text_color = isset( $attributes['textColor'] ) ? esc_attr( $attributes['textColor'] ) : ''; + + // Build inline styles. + $styles = array(); + if ( $background_color ) { + $styles[] = 'background-color: ' . $background_color; + } + if ( $text_color ) { + $styles[] = 'color: ' . $text_color; + } + $style_attr = ! empty( $styles ) ? ' style="' . esc_attr( implode( '; ', $styles ) ) . '"' : ''; + + // Build CSS classes. + $classes = array( + 'wp-block-lsx-example-block', + 'has-text-align-' . $alignment, + ); + + // Output the block. + ob_start(); + ?> +
{__('Customize your example block appearance.', 'lsx-theme')}
+