Contributing to LARC

Thank you for your interest in contributing to LARC! We welcome contributions from the community.

📋 Table of Contents

• Code of Conduct
• Getting Started
• Repository Structure
• Development Workflow
• Pull Request Process
• Coding Standards
• Testing Guidelines
• Documentation
• Community

Code of Conduct

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.

Getting Started

Prerequisites

• Node.js 18.x or higher
• Git
• A modern web browser (Chrome, Firefox, Safari, or Edge)

Setting Up the Development Environment

git clone https://github.com/larcjs/larc.git
   cd larc

npm install

./setup.sh      # Mac/Linux
   # OR
   setup.bat       # Windows

python3 -m http.server 8000
   # OR
   npx serve

Repository Structure

LARC is organized as an npm workspaces monorepo:

larc/
├── packages/                      # Published packages (npm workspaces)
│   ├── core/                      # @larcjs/core
│   ├── components/                # @larcjs/ui
│   ├── core-lite/                 # @larcjs/core-lite
│   ├── core-routing/              # @larcjs/core-routing
│   ├── core-debug/                # @larcjs/core-debug
│   ├── core-types/                # @larcjs/core-types
│   └── components-types/          # @larcjs/ui-types
├── apps/                          # Demo applications
├── examples/                      # Code examples
├── devtools/                      # Chrome DevTools extension
├── cli/                           # create-larc-app CLI
├── react-adapter/                 # React integration
├── registry/                      # Component registry
├── vscode-extension/              # VS Code extension
├── docs/                          # Documentation & guides
└── playground/                    # Interactive component explorer

Where to Contribute

All packages are in this monorepo. Choose the appropriate directory based on your contribution:

| Contribution Type | Directory | |------------------|-----------| | Core messaging bus, autoloader | packages/core/ | | TypeScript types for core | packages/core-types/ | | UI components | packages/ui/ | | TypeScript types for components | packages/ui-types/ | | Example applications | examples/ | | Documentation website | docs/site/ | | DevTools extension | devtools/ | | CLI tool | cli/ | | React adapter | react-adapter/ | | Playground, config, docs | Root directory |

Development Workflow

1. Fork and Branch

# Fork the appropriate repository on GitHub, then:
git clone https://github.com/YOUR_USERNAME/REPO_NAME.git
cd REPO_NAME
git checkout -b feature/your-feature-name

2. Make Changes

• Write clear, concise code
• Follow the existing code style
• Add tests for new features
• Update documentation as needed

3. Test Your Changes

cd core
npm install
npm test

cd ui
npm install
npm test

• Test in multiple browsers
• Verify all links work
• Check mobile responsiveness

4. Commit Your Changes

Follow conventional commit format:

git commit -m "feat: add new pan-wizard component"
git commit -m "fix: resolve memory leak in pan-bus"
git commit -m "docs: update API reference for pan-client"
git commit -m "test: add tests for message routing"

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation only
• style: - Code style changes (formatting, no logic change)
• refactor: - Code refactoring
• test: - Adding or updating tests
• chore: - Maintenance tasks

Version Management & Changesets

We use Changesets for managing versions and publishing packages. If your contribution changes functionality or fixes bugs in a published package, you need to create a changeset.

When to Create a Changeset

Create a changeset if your PR:

• Adds a new feature
• Fixes a bug
• Makes breaking changes
• Updates dependencies that affect functionality

• Documentation-only changes
• Internal refactoring without behavior changes
• Example updates
• Test additions

How to Create a Changeset

npm run changeset

git add .changeset
   git commit -m "feat: add new feature with changeset"

Example Changeset Workflow

# Make your changes
vim packages/core/src/pan-bus.mjs

# Create a changeset
npm run changeset
# Select: @larcjs/core
# Type: minor (new feature)
# Summary: "Add support for wildcard message subscriptions"

# Commit everything together
git add packages/core .changeset
git commit -m "feat(core): add wildcard subscriptions"
git push

Automated Release Process

When your PR with a changeset is merged:

Pull Request Process

Before Submitting

• [ ] All tests pass locally
• [ ] Code follows project style guidelines
• [ ] Documentation is updated
• [ ] Commit messages are clear and follow conventions
• [ ] No console.log statements left in code
• [ ] TypeScript types are updated (if applicable)

Submitting a PR

git push origin feature/your-feature-name

## Description
   Brief description of changes

   ## Type of Change
   - [ ] Bug fix
   - [ ] New feature
   - [ ] Breaking change
   - [ ] Documentation update

   ## Testing
   - [ ] Tests pass locally
   - [ ] Tested in Chrome
   - [ ] Tested in Firefox
   - [ ] Tested in Safari
   - [ ] Tested on mobile

   ## Related Issues
   Fixes #123

   ## Screenshots (if applicable)

Review Process

• Maintainers will review your PR within 1-3 business days
• Address any requested changes
• Once approved, a maintainer will merge your PR
• Your contribution will be included in the next release

Coding Standards

JavaScript/ES Modules

• Use ES modules (.mjs extension for core files)
• Use modern JavaScript (ES2020+)
• Avoid dependencies when possible
• Prefer const over let, avoid var
• Use arrow functions for callbacks
• Use template literals for strings

// Good
const client = new PanClient();
const message = { topic: 'user.updated', data: { id: 123 } };
client.publish(message);

// Bad
var client = new PanClient();
var message = { topic: 'user.updated', data: { id: 123 } };
client.publish(message);

Web Components

• Extend HTMLElement
• Use Shadow DOM for encapsulation
• Clean up subscriptions in disconnectedCallback
• Use descriptive attribute names
• Document all attributes and events

class PanCard extends HTMLElement {
  connectedCallback() {
    this.attachShadow({ mode: 'open' });
    this.client = new PanClient(this);
    this.render();
  }

  disconnectedCallback() {
    this.client?.destroy();
  }

  render() {
    this.shadowRoot.innerHTML = `<div class="card">...</div>`;
  }
}

CSS

• Use CSS custom properties for theming
• Follow BEM naming conventions
• Keep specificity low
• Mobile-first responsive design

TypeScript

• Keep type definitions in separate repos
• Export all public types
• Use JSDoc for documentation
• Avoid any type

Testing Guidelines

Core Package Tests

• Use Playwright for browser testing
• Test across multiple browsers (Chromium, Firefox, WebKit)
• Cover edge cases and error conditions
• Test async behavior thoroughly

import { test, expect } from '@playwright/test';

test('should publish and deliver message', async ({ page }) => {
  await page.goto('/test.html');

  const result = await page.evaluate(() => {
    const client = new PanClient();
    return new Promise(resolve => {
      client.subscribe('test.topic', msg => resolve(msg));
      client.publish({ topic: 'test.topic', data: { value: 42 } });
    });
  });

  expect(result.data.value).toBe(42);
});

UI Component Tests

All major UI components have comprehensive test coverage including:

• Component registration and rendering
• Attribute changes and reactivity
• PAN message handling
• Shadow DOM functionality
• Cross-browser compatibility

• Test custom element registration
• Test attribute changes trigger updates
• Test slot content projection
• Test PAN bus message subscriptions
• Test accessibility (ARIA labels, keyboard navigation)

Test Coverage

• ✅ Core package: 335 tests passing, 80%+ code coverage
• ✅ UI package: 165 tests passing across 3 browsers
• 100% coverage for critical paths
• All public APIs must be tested
• Edge cases and error handling must be tested

Documentation

Code Documentation

• Add JSDoc comments to all public APIs
• Include examples in JSDoc
• Document parameters, return values, and exceptions
• Keep comments up to date

/**
 * Publishes a message to the PAN bus
 *
 * @param {Object} message - Message to publish
 * @param {string} message.topic - Topic name (e.g., 'user.updated')
 * @param {*} message.data - Message payload
 * @param {boolean} [message.retained=false] - Whether to retain message
 *
 * @returns {Promise<void>} Resolves when message is published
 *
 * @example
 * await client.publish({
 *   topic: 'user.updated',
 *   data: { id: 123, name: 'John' }
 * });
 */
async publish(message) {
  // Implementation
}

Markdown Documentation

• Update relevant docs when changing APIs
• Include code examples
• Use clear headings and structure
• Add a table of contents for long documents

Component Documentation

Every component should have:

• Description of purpose
• List of attributes
• List of events
• Usage examples
• Accessibility notes

Community

Getting Help

• 💬 Discord - Chat with the community
• 💬 GitHub Discussions - Ask questions, share ideas
• 🐛 GitHub Issues - Report bugs
• 📖 Documentation - Read the docs

Reporting Bugs

When reporting bugs, please include:

**Description:**
Brief description of the bug

**Steps to Reproduce:**
1. Load page with pan-bus
2. Subscribe to topic
3. Publish message
4. See error

**Expected Behavior:**
Message should be delivered

**Actual Behavior:**
Error is thrown

**Environment:**
- Browser: Chrome 120
- LARC: v1.1.1
- OS: macOS 14

**Code Sample:**
\`\`\`javascript
const client = new PanClient();
client.subscribe('test', msg => console.log(msg));
\`\`\`

**Screenshots:**
[Attach if applicable]

Suggesting Features

Before suggesting a feature:

• Check if it already exists
• Search existing issues and discussions
• Consider if it fits LARC's philosophy

• Explain the use case
• Provide examples
• Consider backward compatibility
• Be open to feedback

Recognition

Contributors will be:

• Listed in release notes
• Added to CONTRIBUTORS.md (if you make substantial contributions)
• Credited in documentation (for significant docs contributions)

Questions?

Feel free to:

• Open a Discussion
• Comment on an existing issue
• Reach out to maintainers