@planningcenter/eslint-plugin-tapestry 0.1.0

package/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @planningcenter/design-engineering

package/.github/workflows/linting.yml

@@ -0,0 +1,26 @@
+name: Linting
+
+on: [pull_request]
+
+jobs:
+  linting:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      checks: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "yarn"
+      - run: yarn install
+      - uses: planningcenter/balto-typescript@v1.2.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          conclusionLevel: "failure"
+      - uses: reviewdog/action-eslint@v1
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          reporter: github-pr-check

package/.github/workflows/pco-release-create-pr.yml

@@ -0,0 +1,23 @@
+name: PCO-Release - Release Automation
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-automation:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "yarn"
+      - uses: planningcenter/pco-release-action/release-by-pr@v1
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/pco-release-create-prerelease.yml

@@ -0,0 +1,27 @@
+name: Create Pre-Release
+on:
+  issue_comment:
+    types: [created]
+
+jobs:
+  create-rc-release:
+    if: github.event.issue.pull_request && contains(github.event.comment.body, '@pco-release rc')
+    uses: planningcenter/pco-release-action/.github/workflows/release-candidate.yml@v1
+    secrets: inherit
+    permissions:
+      contents: write
+      pull-requests: write
+      packages: write
+    with:
+      only: accounts,calendar,check-ins,giving,groups,home,people,registrations,services
+
+  create-qa-release:
+    if: github.event.issue.pull_request && contains(github.event.comment.body, '@pco-release qa')
+    permissions:
+      contents: write
+      pull-requests: write
+      packages: write
+    uses: planningcenter/pco-release-action/.github/workflows/qa-release.yml@v1
+    secrets: inherit
+    with:
+      only: accounts,calendar,check-ins,giving,groups,home,people,registrations,services

package/.github/workflows/pco-release-create-release-on-merge.yml

@@ -0,0 +1,19 @@
+name: PCO-Release - Create Release on Merge
+
+on:
+  pull_request:
+    types: [closed]
+    branches:
+      - main
+
+jobs:
+  create-release:
+    if: github.event.pull_request.merged == true && contains(github.event.pull_request.labels.*.name, 'pco-release-pending')
+    permissions:
+      contents: write
+      pull-requests: write
+      packages: write
+    uses: planningcenter/pco-release-action/.github/workflows/release.yml@v1
+    secrets: inherit
+    with:
+      pr-number: ${{ github.event.pull_request.number }}

package/.github/workflows/pco-release-require-changelog-update.yml

@@ -0,0 +1,22 @@
+name: PCO-Release - Require Changelog Update
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  require-changelog-update:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: read
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - id: changed-files
+        uses: tj-actions/changed-files@v46
+        with:
+          files: CHANGELOG.md
+      - if: steps.changed-files.outputs.any_changed == 'false'
+        run: |
+          echo "Pull Requests require an update to the CHANGELOG.md file."
+          exit 1

package/.github/workflows/pco-release-sync-release-by-label.yml

@@ -0,0 +1,19 @@
+name: PCO-Release - Sync With Labels
+
+on:
+  pull_request:
+    types: [labeled]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  sync-with-labels:
+    if: ${{ github.event.pull_request.head.ref == 'pco-release--internal' && (github.event.label.name == 'pco-release-patch' || github.event.label.name == 'pco-release-minor' || github.event.label.name == 'pco-release-major') }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: planningcenter/pco-release-action/sync-with-labels@v1
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/revert.yml

@@ -0,0 +1,21 @@
+name: Revert
+on:
+  workflow_dispatch:
+    inputs:
+      release-tag:
+        description: "Version to deploy"
+        required: true
+      pr-number:
+        description: "Pull Request number to post results of results"
+        required: true
+
+jobs:
+  revert:
+    permissions:
+      contents: write
+      pull-requests: write
+    secrets: inherit
+    uses: planningcenter/pco-release-action/.github/workflows/revert.yml@v1
+    with:
+      release-tag: ${{ inputs.release-tag }}
+      pr-number: ${{ inputs.pr-number }}

package/.github/workflows/tests.yml

@@ -0,0 +1,22 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - "**"
+      - "!main"
+
+jobs:
+  run-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "yarn"
+      - run: yarn install
+      - name: Run eslint
+        run: yarn lint

package/README.md

@@ -0,0 +1,110 @@
+# eslint-plugin-tapestry
+
+ESLint plugin for Tapestry components to encourage best practices and accessibility.
+
+> This plugin only tests components provided by Tapestry; it will ignore native HTML elements, Tapestry-React, etc.
+
+## Installation
+
+```bash
+yarn add @planningcenter/eslint-plugin-tapestry --dev
+```
+
+## Configuration
+
+### Recommended Configuration
+
+#### Flat Config
+```javascript
+import tapestry from '@planningcenter/eslint-plugin-tapestry';
+
+export default [
+  tapestry.configs.recommended,
+];
+```
+
+#### Legacy Config
+```json
+"plugins": [
+  "tapestry"
+],
+...
+{
+  "extends": ["plugin:tapestry/recommended"]
+}
+```
+
+### ESLint Flat Config (eslint.config.js)
+
+```javascript
+import tapestry from '@planningcenter/eslint-plugin-tapestry';
+
+export default [
+  {
+    plugins: {
+      tapestry,
+    },
+    rules: {
+      'tapestry/valid-href': 'error',
+    },
+  },
+];
+```
+
+### Legacy Config (.eslintrc.json)
+
+```json
+{
+  "plugins": ["tapestry"],
+  "rules": {
+    "tapestry/valid-href": "error"
+  }
+}
+```
+
+## Rules
+
+| Rule | Category | Description |
+| ---- | -------- | ----------- |
+| [valid-href](docs/rules/valid-href.md) | Accessibility | Ensures that `BaseLink`, `Link`, and `IconLink` components have valid `href` values |
+
+## Development
+
+```bash
+yarn test          # Run tests
+yarn test --watch  # Run tests in watch mode
+```
+
+## Setup for initial release testing
+
+### Tapestry
+1. Open a terminal to this repo and run `yarn && yalc publish`
+2. Open a new terminal to Tapestry and create a temp test branch from `main`
+3. Run `yalc add @planningcenter/eslint-plugin-tapestry@1.0.0 --dev`
+5. In `eslint.config.mjs`, add or modify
+  * `import tapestry from "@planningcenter/eslint-plugin-tapestry"`
+  * `plugins: {tapestry}`
+  * `rules: {"tapestry/valid-href": "error"}`
+6. Restart the ESLint server (`cmd` + `shift` + `P` > `ESLint: Restart Eslint Server`)
+7. Open `packages/tapestry/src/components/link/index.stories.tsx` and notice that the `tapestry-react` `Link` isn't reporting any lint errors (no red squiggle lines)
+8. Comment out the `Link` import and add a line to `import { Link } from "@planningcenter/tapestry"`
+    * You should get red squiggle lines on the `Link`
+    * Test out different variations of `href` to see the lint errors
+9. In your terminal, run `yarn lint`, notice you'll see `tapestry/valid-href` errors
+
+### Groups
+
+1. Open a terminal to this repo and run `yarn && yalc publish`
+2. Open a new terminal to Groups and create a temp test branch from `main`
+3. Run `yalc add @planningcenter/eslint-plugin-tapestry@1.0.0 --dev`
+5. In `eslint.config.mjs`, add or modify
+  * `import tapestry from "@planningcenter/eslint-plugin-tapestry"`
+  * `plugins: {tapestry}`
+  * `rules: {"tapestry/valid-href": "error"}`
+  * `files: ["**/*.ts", "**/*.tsx", "**/*.jsx", "**/*.js"],`
+6. Restart the ESLint server (`cmd` + `shift` + `P` > `ESLint: Restart Eslint Server`)
+7. Open `app/javascript/staff_only/staff_only_nav_links.tsx` and notice that the `tapestry-react` `Link` isn't reporting any lint errors (no red squiggle lines)
+8. Comment out the `Link` import and add a line to `import { Link } from "@planningcenter/tapestry"`
+    * You should get red squiggle lines on the `Link`
+    * Test out different variations of `href` to see the lint errors
+9. In your terminal, run `yarn lint`, notice you'll see `tapestry/valid-href` errors

package/docs/rules/valid-href.md

@@ -0,0 +1,82 @@
+# valid-href
+
+Ensures that `BaseLink`, `Link`, `IconLink` components have valid `href` values.
+
+## Rule Details
+
+This rule enforces that Tapestry link components (`BaseLink`, `Link`, and `IconLink`) have valid `href` values to ensure proper accessibility support for keyboard navigation and screen readers.
+
+### Requirements
+
+- ✅ `href` must be specified as a direct prop (not in spread props)
+- ✅ `href` cannot be empty string `""`
+- ✅ `href` cannot be just a hash `"#"`
+- ✅ `href` cannot contain `javascript`
+
+## Examples
+
+### ❌ Invalid
+
+```jsx
+// Missing href
+<BaseLink>Click me</BaseLink>
+
+// Invalid href values
+<Link href="">Empty</Link>
+<Link href="#">Hash only</Link>
+<Link href="javascript:void(0)">JS void</Link>
+
+// href in spread props
+<IconLink {...props}>Icon</IconLink>
+```
+
+### ✅ Valid
+
+```jsx
+<BaseLink href="/page">Click me</BaseLink>
+<Link href="https://example.com">External</Link>
+<IconLink href="/dashboard">Dashboard</IconLink>
+<Link href="mailto:test@example.com">Email</Link>
+<IconLink href="tel:555-1234">Call</IconLink>
+```
+
+## Configuration
+
+This rule is enabled by default in the recommended configuration.
+
+```json
+{
+  "rules": {
+    "tapestry/valid-href": "error"
+  }
+}
+```
+
+## Background
+
+In HTML and React, the `href` attribute in anchor tags is defined as either a `string` or `undefined` by default. This flexibility, while convenient, can lead to accessibility and user experience issues when improper values are used. This RFC addresses why enforcing proper `href` values is crucial.
+
+The `href` attribute is a critical component of HTML anchor tags for several reasons:
+
+### Accessibility Considerations
+
+- **Screen Reader Navigation:** Screen readers announce links and their destinations to users. Without a valid `href`, screen readers might announce it as "link to nowhere" or skip it entirely.
+- **Keyboard Navigation:** The `href` attribute makes links naturally focusable and interactive with keyboard navigation. Links without proper hrefs break this expected behavior.
+- **Semantic Clarity:** A proper `href` communicates the purpose of the link to assistive technologies, helping users understand where they'll go when activating it.
+
+### User Experience & Performance
+
+- **Expected Behavior:** Users expect clicking a link to navigate somewhere. Empty or JavaScript-based pseudo-links (`href="#"` or `href="javascript:void(0)"`) frustrate this expectation.
+- **Browser Optimizations:** Browsers can pre-fetch content from valid URLs, improving page transition speed and responsiveness.
+- **Default Link Behaviors:** Proper `href`s enable right-click context menus, "open in new tab," and other browser features users rely on.
+
+### Technical Benefits
+
+- **Analytics:** Most analytics tools track link clicks based on href values, helping understand user navigation patterns.
+- **History Management:** Real URLs properly update browser history, enabling back/forward navigation and bookmarking.
+- **Testing:** Valid `href`s make automated testing more reliable, as tools can verify navigation paths.
+
+## Further Reading
+
+- [Web Content Accessibility Guidelines (WCAG) on Links](https://www.w3.org/WAI/WCAG21/Understanding/link-purpose-in-context.html)
+- [MDN: HTMLAnchorElement.href](https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/href)

package/index.js

@@ -0,0 +1,27 @@
+const validHrefRule = require('./rules/valid-href');
+
+module.exports = {
+  rules: {
+    'valid-href': validHrefRule,
+  },
+  configs: {
+    recommended: {
+      plugins: ['tapestry'],
+      rules: {
+        'tapestry/valid-href': 'error',
+      },
+    },
+    // Legacy configuration for .eslintrc.json
+    legacy: {
+      plugins: ['tapestry'],
+      rules: {
+        'tapestry/valid-href': 'error',
+      },
+    },
+  },
+  // Flat config support for eslint.config.js
+  meta: {
+    name: 'eslint-plugin-tapestry',
+    version: '1.0.0',
+  },
+};

package/jest.config.js

@@ -0,0 +1,8 @@
+module.exports = {
+  testEnvironment: 'node',
+  testMatch: ['**/tests/**/*.test.js'],
+  collectCoverageFrom: [
+    'rules/**/*.js',
+    'index.js',
+  ],
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@planningcenter/eslint-plugin-tapestry",
+  "version": "0.1.0",
+  "description": "ESLint plugin for Tapestry React components",
+  "repository": "https://github.com/planningcenter/eslint-plugin-tapestry.git",
+  "main": "index.js",
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "tapestry",
+    "react",
+    "accessibility"
+  ],
+  "author": "Planning Center",
+  "license": "UNLICENSED",
+  "devDependencies": {
+    "@babel/core": "^7.23.0",
+    "@babel/preset-env": "^7.23.0",
+    "@babel/preset-react": "^7.22.0",
+    "eslint": "^8.50.0",
+    "jest": "^29.7.0"
+  },
+  "peerDependencies": {
+    "eslint": ">=8.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/rules/valid-href.js

@@ -0,0 +1,117 @@
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Ensure BaseLink, Link, IconLink components have valid href values',
+      category: 'Accessibility',
+      recommended: true,
+      url: 'https://github.com/planningcenter/eslint-plugin-tapestry/blob/main/docs/rules/valid-href.md',
+    },
+    fixable: null,
+    schema: [],
+    messages: {
+      missingHref: 'Tapestry {{componentName}} component must have an href prop',
+      invalidHref: 'Tapestry {{componentName}} component href cannot be "{{value}}" - use a valid URL, path, or Button component instead.',
+      hrefInSpread: 'Tapestry {{componentName}} component href must be specified as a direct prop, not in spread props',
+    },
+  },
+
+  create(context) {
+    const targetComponents = new Set(['BaseLink', 'Link', 'IconLink']);
+    const invalidHrefValues = new Set(['', '#']);
+    const tapestryImports = new Set();
+
+    function isJavaScriptUrl(value) {
+      if (typeof value !== 'string') return false;
+      return value.toLowerCase().includes('javascript');
+    }
+
+    function isTapestryComponent(componentName) {
+      // Only check Tapestry components if imported from current Tapestry
+      return tapestryImports.has(componentName);
+    }
+
+    function checkHrefProp(node, componentName) {
+      let hasDirectHref = false;
+      let hasSpreadProps = false;
+      let hrefValue = null;
+
+      // Check for direct href prop
+      for (const prop of node.attributes) {
+        if (prop.type === 'JSXAttribute' && prop.name.name === 'href') {
+          hasDirectHref = true;
+          
+          // Extract href value for validation
+          if (prop.value) {
+            if (prop.value.type === 'Literal') {
+              hrefValue = prop.value.value;
+            } else if (prop.value.type === 'JSXExpressionContainer') {
+              if (prop.value.expression.type === 'Literal') {
+                hrefValue = prop.value.expression.value;
+              }
+            }
+          }
+        } else if (prop.type === 'JSXSpreadAttribute') {
+          hasSpreadProps = true;
+        }
+      }
+
+      // Report missing href
+      if (!hasDirectHref && !hasSpreadProps) {
+        context.report({
+          node,
+          messageId: 'missingHref',
+          data: { componentName },
+        });
+        return;
+      }
+
+      // Report href in spread props
+      if (!hasDirectHref && hasSpreadProps) {
+        context.report({
+          node,
+          messageId: 'hrefInSpread',
+          data: { componentName },
+        });
+        return;
+      }
+
+      // Validate href value if we have one
+      if (hasDirectHref && hrefValue !== null) {
+        if (invalidHrefValues.has(hrefValue) || isJavaScriptUrl(hrefValue)) {
+          context.report({
+            node,
+            messageId: 'invalidHref',
+            data: { 
+              componentName,
+              value: hrefValue 
+            },
+          });
+        }
+      }
+    }
+
+    return {
+      ImportDeclaration(node) {
+        // Track imports from @planningcenter/tapestry
+        if (node.source.value === '@planningcenter/tapestry') {
+          node.specifiers.forEach(spec => {
+            if (spec.type === 'ImportSpecifier') {
+              tapestryImports.add(spec.imported.name);
+            }
+          });
+        }
+      },
+
+      JSXOpeningElement(node) {
+        if (node.name.type === 'JSXIdentifier') {
+          const componentName = node.name.name;
+          
+          if (targetComponents.has(componentName) && isTapestryComponent(componentName)) {
+            checkHrefProp(node, componentName);
+          }
+        }
+      },
+    };
+  },
+};

package/tests/valid-href.test.js

@@ -0,0 +1,208 @@
+const { RuleTester } = require('eslint');
+const rule = require('../rules/valid-href');
+
+const ruleTester = new RuleTester({
+  parserOptions: {
+    ecmaVersion: 2018,
+    sourceType: 'module',
+    ecmaFeatures: {
+      jsx: true,
+    },
+  },
+});
+
+ruleTester.run('valid-href', rule, {
+  valid: [
+    // Valid href values - Tapestry components with imports
+    {
+      code: `
+        import { BaseLink } from '@planningcenter/tapestry';
+        <BaseLink href="/page">Click me</BaseLink>
+      `,
+    },
+    {
+      code: `
+        import { Link } from '@planningcenter/tapestry';
+        <Link href="https://example.com">External</Link>
+      `,
+    },
+    {
+      code: `
+        import { IconLink } from '@planningcenter/tapestry';
+        <IconLink href="/dashboard">Dashboard</IconLink>
+      `,
+    },
+
+    // Legacy components should be ignored (no @planningcenter/tapestry import)
+    {
+      code: `
+        import { Link } from 'tapestry-react';
+        <Link href="#">Legacy component ignored</Link>
+      `,
+    },
+    {
+      code: `
+        import { Link } from '@planningcenter/tapestry-react';
+        <Link href="#">Legacy component ignored</Link>
+      `,
+    },
+
+    // Components that aren't target components should be ignored
+    '<Button>Click me</Button>',
+    '<CustomLink href="#">Custom component</CustomLink>',
+
+    // Dynamic href values (we can't validate these statically)
+    {
+      code: `
+        import { BaseLink, Link } from '@planningcenter/tapestry';
+        <div>
+          <BaseLink href={dynamicHref}>Dynamic</BaseLink>
+          <Link href={\`/user/\${userId}\`}>Template literal</Link>
+        </div>
+      `,
+    },
+  ],
+
+  invalid: [
+    // Missing href - Tapestry components (with imports)
+    {
+      code: `
+        import { BaseLink } from '@planningcenter/tapestry';
+        <BaseLink>Click me</BaseLink>
+      `,
+      errors: [{
+        messageId: 'missingHref',
+        data: { componentName: 'BaseLink' },
+      }],
+    },
+    {
+      code: `
+        import { Link } from '@planningcenter/tapestry';
+        <Link>External</Link>
+      `,
+      errors: [{
+        messageId: 'missingHref',
+        data: { componentName: 'Link' },
+      }],
+    },
+    {
+      code: `
+        import { IconLink } from '@planningcenter/tapestry';
+        <IconLink>Dashboard</IconLink>
+      `,
+      errors: [{
+        messageId: 'missingHref',
+        data: { componentName: 'IconLink' },
+      }],
+    },
+
+    // Empty href - Tapestry components
+    {
+      code: `
+        import { BaseLink } from '@planningcenter/tapestry';
+        <BaseLink href="">Empty</BaseLink>
+      `,
+      errors: [{
+        messageId: 'invalidHref',
+        data: { componentName: 'BaseLink', value: '' },
+      }],
+    },
+    {
+      code: `
+        import { Link } from '@planningcenter/tapestry';
+        <Link href={""}>Empty expression</Link>
+      `,
+      errors: [{
+        messageId: 'invalidHref',
+        data: { componentName: 'Link', value: '' },
+      }],
+    },
+
+    // Hash only - Tapestry components
+    {
+      code: `
+        import { BaseLink } from '@planningcenter/tapestry';
+        <BaseLink href="#">Hash only</BaseLink>
+      `,
+      errors: [{
+        messageId: 'invalidHref',
+        data: { componentName: 'BaseLink', value: '#' },
+      }],
+    },
+    {
+      code: `
+        import { IconLink } from '@planningcenter/tapestry';
+        <IconLink href={"#"}>Hash expression</IconLink>
+      `,
+      errors: [{
+        messageId: 'invalidHref',
+        data: { componentName: 'IconLink', value: '#' },
+      }],
+    },
+
+    // JavaScript URLs - Tapestry components
+    {
+      code: `
+        import { BaseLink } from '@planningcenter/tapestry';
+        <BaseLink href="javascript:void(0)">JS void</BaseLink>
+      `,
+      errors: [{
+        messageId: 'invalidHref',
+        data: { componentName: 'BaseLink', value: 'javascript:void(0)' },
+      }],
+    },
+    {
+      code: `
+        import { Link } from '@planningcenter/tapestry';
+        <Link href="javascript:alert('hi')">JS alert</Link>
+      `,
+      errors: [{
+        messageId: 'invalidHref',
+        data: { componentName: 'Link', value: 'javascript:alert(\'hi\')' },
+      }],
+    },
+    {
+      code: `
+        import { IconLink } from '@planningcenter/tapestry';
+        <IconLink href="JavaScript:void(0)">Uppercase JS</IconLink>
+      `,
+      errors: [{
+        messageId: 'invalidHref',
+        data: { componentName: 'IconLink', value: 'JavaScript:void(0)' },
+      }],
+    },
+
+    // href in spread props - Tapestry components
+    {
+      code: `
+        import { BaseLink } from '@planningcenter/tapestry';
+        <BaseLink {...props}>Spread props</BaseLink>
+      `,
+      errors: [{
+        messageId: 'hrefInSpread',
+        data: { componentName: 'BaseLink' },
+      }],
+    },
+    {
+      code: `
+        import { Link } from '@planningcenter/tapestry';
+        <Link {...linkProps} className="link">Spread with other props</Link>
+      `,
+      errors: [{
+        messageId: 'hrefInSpread',
+        data: { componentName: 'Link' },
+      }],
+    },
+    {
+      code: `
+        import { IconLink } from '@planningcenter/tapestry';
+        <IconLink {...rest} aria-label="Icon">Icon with spread</IconLink>
+      `,
+      errors: [{
+        messageId: 'hrefInSpread',
+        data: { componentName: 'IconLink' },
+      }],
+    },
+
+  ],
+});