@wasilabsoftware/jira-extension-plugin

v0.0.3

Published

7 months ago

Web Components for Jira issue management - works with any framework

0High
0Medium
0Low

arodriguezwlb

jira web-components stencil custom-elements issue-management

Jira Extension Plugin

A complete Jira issue management system built as framework-agnostic Web Components using Stencil.

Features

🎯 Complete Jira Integration - View, create, edit, and delete issues
🧩 Framework Agnostic - Works with React, Vue, Angular, or vanilla JavaScript
🎨 Custom Styling - CSS variables for easy theming
📱 Responsive Design - Works on desktop, tablet, and mobile
⚡ Lazy Loading - Components load on demand for optimal performance
🔒 Type Safe - Built with TypeScript for better DX

Components

Main Components

<jira-dashboard> - Complete dashboard with navigation and state management
<jira-issue-table> - Sortable table view of issues
<jira-issue-detail> - Detailed issue view with comments and transitions
<jira-create-issue> - Form to create new issues
<jira-edit-issue> - Form to edit or delete existing issues

Utility Components

<jira-avatar> - User avatar with initials fallback
<jira-status-badge> - Status indicator
<jira-priority-badge> - Priority indicator
<jira-spinner> - Loading spinner
<jira-error> - Error display with retry

Installation

npm install jira-extension-plugin

Usage

Option 1: Complete Dashboard (Recommended)

<!DOCTYPE html>
<html>
<head>
  <script type="module" src="https://unpkg.com/jira-extension-plugin/dist/jira-extension-plugin/jira-extension-plugin.esm.js"></script>
</head>
<body>
  <jira-dashboard
    jira-domain="https://your-domain.atlassian.net"
    jira-email="[email protected]"
    jira-token="your-jira-api-token"
    api-token="your-external-api-token"
    api-base-url="https://your-api.workers.dev"
    project-key="PROJ"
    board-id="123"
    initial-view="backlog">
  </jira-dashboard>
</body>
</html>

Option 2: Individual Components

<!-- Issue Table -->
<jira-issue-table
  jira-domain="https://your-domain.atlassian.net"
  jira-email="[email protected]"
  jira-token="your-jira-api-token"
  api-token="your-external-api-token"
  api-base-url="https://your-api.workers.dev"
  project-key="PROJ"
  sprint-type="backlog">
</jira-issue-table>

<!-- Issue Detail -->
<jira-issue-detail
  jira-domain="https://your-domain.atlassian.net"
  jira-email="[email protected]"
  jira-token="your-jira-api-token"
  api-token="your-external-api-token"
  api-base-url="https://your-api.workers.dev"
  issue-key="PROJ-123"
  editable="true">
</jira-issue-detail>

Framework Integration

React

For React applications, install the dedicated React wrapper package:

npm install jira-extension-plugin-react

import { JiraDashboard } from 'jira-extension-plugin-react';

function App() {
  return (
    <JiraDashboard
      jiraDomain="https://your-domain.atlassian.net"
      jiraEmail="[email protected]"
      jiraToken="your-jira-api-token"
      apiToken="your-external-api-token"
      apiBaseUrl="https://your-api.workers.dev"
      projectKey="PROJ"
      boardId="123"
      initialView="backlog"
      onIssueSelected={(e) => console.log(e.detail)}
    />
  );
}

See jira-extension-plugin-react on npm for more details.

Vue

<template>
  <jira-dashboard
    :jira-domain="jiraDomain"
    :jira-email="jiraEmail"
    :jira-token="jiraToken"
    :api-token="apiToken"
    :api-base-url="apiBaseUrl"
    :project-key="projectKey"
    :board-id="boardId"
    initial-view="backlog"
  />
</template>

<script>
import { defineCustomElements } from 'jira-extension-plugin/loader';

defineCustomElements();

export default {
  data() {
    return {
      jiraDomain: 'https://your-domain.atlassian.net',
      jiraEmail: '[email protected]',
      jiraToken: 'your-jira-api-token',
      apiToken: 'your-external-api-token',
      apiBaseUrl: 'https://your-api.workers.dev',
      projectKey: 'PROJ',
      boardId: '123'
    };
  }
};
</script>

Configuration

Authentication Props (Required for all components)

| Prop | Type | Description | |------|------|-------------| | jira-domain | string | Your Jira domain (e.g., https://yourcompany.atlassian.net) | | jira-email | string | Email associated with your Jira account | | jira-token | string | Jira API token (create one here) | | api-token | string | External API token for your Cloudflare Workers proxy | | api-base-url | string | Base URL of your Cloudflare Workers API |

Component-Specific Props

`<jira-dashboard>`

| Prop | Type | Default | Description | |------|------|---------|-------------| | project-key | string | - | Jira project key (e.g., "VINM") | | board-id | string | - | Board ID for sprint view (optional) | | initial-view | 'backlog' \| 'current-sprint' \| 'all' | 'backlog' | Initial view to display |

`<jira-issue-table>`

| Prop | Type | Default | Description | |------|------|---------|-------------| | project-key | string | - | Jira project key | | sprint-type | 'backlog' \| 'current-sprint' \| 'all' | 'backlog' | Which issues to display | | board-id | string | - | Required for current-sprint type | | max-results | number | 50 | Maximum issues to fetch |

`<jira-issue-detail>`

| Prop | Type | Default | Description | |------|------|---------|-------------| | issue-key | string | - | Issue key to display (e.g., "VINM-123") | | editable | boolean | true | Show edit button |

`<jira-create-issue>` / `<jira-edit-issue>`

| Prop | Type | Default | Description | |------|------|---------|-------------| | project-key | string | - | Jira project key (create only) | | issue-key | string | - | Issue key to edit (edit only) |

Events

All components emit custom events that you can listen to:

const dashboard = document.querySelector('jira-dashboard');

// Issue selected in table
dashboard.addEventListener('issueSelected', (e) => {
  console.log('Selected issue:', e.detail.issueKey);
});

// Issue created
dashboard.addEventListener('issueCreated', (e) => {
  console.log('Created issue:', e.detail.issueKey);
});

// Issue updated
dashboard.addEventListener('issueUpdated', (e) => {
  console.log('Updated issue:', e.detail.issueKey);
});

// Issue deleted
dashboard.addEventListener('issueDeleted', (e) => {
  console.log('Deleted issue:', e.detail.issueKey);
});

// Load errors
dashboard.addEventListener('loadError', (e) => {
  console.error('Error:', e.detail.message);
});

Custom Fields

The components support two hardcoded custom fields:

Story Points: customfield_10016
Pricing: customfield_10091

To modify these or add more custom fields, edit src/types/jira.types.ts.

Styling & Theming

Components use CSS custom properties for theming. Override these in your CSS:

:root {
  --jira-color-primary: #0052cc;
  --jira-color-text-primary: #172b4d;
  --jira-font-family: 'Your Font', sans-serif;
  /* ... see src/global/variables.css for all available variables */
}

API Requirements

This library requires a backend API (Cloudflare Workers recommended) that proxies requests to Jira. See API.md for the complete API specification.

Required endpoints:

GET /api/v1/issues/backlog?project={key}
GET /api/v1/issues/current-sprint?boardId={id}
GET /api/v1/issues/{key}
POST /api/v1/issues
PUT /api/v1/issues/{key}
DELETE /api/v1/issues/{key}
GET /api/v1/issues/{key}/comments
POST /api/v1/issues/{key}/comments
GET /api/v1/issues/{key}/transitions
POST /api/v1/issues/{key}/transitions
GET /api/v1/project/metadata?project={key}

Development

Setup

npm install
npm start

Visit http://localhost:3333 to see the components in action.

Build

npm run build

Test

npm test

Generate New Component

npm run generate

Documentation

CLAUDE.md - Complete technical documentation for AI assistants
API.md - API endpoint specification
demo.html - Interactive demo page

Component Documentation

Auto-generated documentation for each component:

Browser Support

Chrome (latest)
Firefox (latest)
Safari (latest)
Edge (latest)

License

MIT

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Support

For issues and questions, please use the GitHub Issues page.