Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 90 additions & 0 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ For detailed information on issue and pull request statuses, process for testing
- **Clone your Fork**: Clone your forked repository to your local machine using Git. This will create a local copy of the project you can work on.
- **Create a Branch**: Create a new branch for your specific contribution. This helps keep your changes isolated and organized.

No contributor license agreement or sign-off is required. As stated in the [GitHub Terms of Service](https://docs.github.com/en/site-policy/github-terms/github-terms-of-service#6-contributions-under-repository-license), your contribution is licensed under the project's [MIT License](../LICENSE), and by submitting it you agree that you have the right to license it under those terms.

## Set up

You will need at least [Node >= 24.0.0](https://nodejs.org/en) installed on your machine.
Expand All @@ -30,6 +32,60 @@ npm ci
npm start
```

## Development workflow

### Linting and formatting

To scan the project for linting errors, run:

```sh
npm run lint
```

To automatically fix most linting and formatting errors, run:

```sh
npm run format
```

Linting and formatting also run in a pre-commit hook.

### Type checks and consistency checks

```sh
npm run check
```

This runs every `check-*` script: type checks for the sources, scripts and stories, the import-boundary check, the import-alias check and the third-party notices check.

### Testing with Web Test Runner

To run the suite of Web Test Runner tests, run:

```sh
npm run test
```

To run the tests in watch mode, run:

```sh
npm run test:watch
```

### Demoing with Storybook

To start a local instance of Storybook for your component, run:

```sh
npm run storybook
```

To build a production version of Storybook, run:

```sh
npm run storybook:build
```

## Making Changes

- **Code Style**: Follow the [existing code style conventions](./CODING_GUIDELINES.md) used in the project. This might involve specific formatting guidelines or linting tools. Refer to the project's codebase or any existing documentation for details.
Expand All @@ -50,6 +106,40 @@ Each component directory holds a `spec.md` describing that component: its overvi
Specifications do not carry ownership, approval or sign-off sections, and the revision history has no author column — `git` already records who changed what. Design hand-off links, such as Figma files, go under `### End-user experience` and are preserved across updates.

A pull request that changes behavior without updating the affected specification is incomplete, and reviewers will ask for it.
- **Changelog**: Add an entry under `[Unreleased]` in [CHANGELOG.md](../CHANGELOG.md) for every user-visible change. The file follows [Keep a Changelog](https://keepachangelog.com/), so use the `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed` and `Security` categories. A fix for a vulnerability goes under `Security`, with a link to the advisory once it is published.

## Accessibility

Accessibility is a requirement, not a feature. See [ACCESSIBILITY.md](../ACCESSIBILITY.md) for the conformance target and the platform constraints that shape how the components expose semantics.

- New and changed component specifications must audit the component with axe, on both its light DOM and its shadow DOM, in each state the specification exercises: `await expect(el).to.be.accessible()` and `await expect(el).shadowDom.to.be.accessible()`.
- Follow the [ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/) pattern for the component's role, including its keyboard interaction. Add keyboard tests for it.
- Publish semantics through `ElementInternals` and ARIA element reflection rather than IDREF attributes, so that relations work across shadow boundaries. Use the controllers under `src/internals/controllers` instead of setting ARIA attributes by hand.
- Disable an axe rule only when it misreports semantics published through internals or element reflection, assert the real relation in the specification instead, and document the exception next to the shared options in `src/internals/testing/helpers.spec.ts`.
- Verify interactive changes by hand with a keyboard and a screen reader before requesting review.

## Dependencies

Runtime dependencies increase the install footprint and the attack surface of every application that uses the library, so they are added rarely and deliberately.

- **Discuss first.** Open an issue or a discussion before adding a runtime dependency or an optional peer dependency. Prefer a small, focused implementation in `src/internals` over a package that does more than the component needs.
- **Licenses.** Runtime and peer dependencies must be licensed under MIT, BSD-2-Clause, BSD-3-Clause, ISC, Apache-2.0, 0BSD or an equivalent permissive license. Copyleft licenses (GPL, LGPL, AGPL, SSPL) are not accepted for anything that ships to consumers. Dual-licensed packages are accepted when one of the options is permissive.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not super sure of the dual bit

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's OK.

- **Manifests.** A runtime dependency is declared in both `package.json` and the published manifest `scripts/_package.json`. Optional peer dependencies are declared with `peerDependenciesMeta.optional: true` in the published manifest.
- **Notices.** After changing a runtime or peer dependency, run `npm run build:notices` and commit the regenerated `THIRD-PARTY-NOTICES.md`. CI fails when the file is out of date. Generation fails for a package that declares a license but ships no license file; copy the text from the package's source repository into `scripts/license-overrides/<package-name>` (with `/` replaced by `__` for scoped packages) and note where it came from in the pull request.
- **Lockfile.** Commit `package-lock.json` changes together with the manifest change. Install with `npm ci`, never `npm install`, so the lockfile stays authoritative.
- **Updates.** Dependabot raises security updates for npm packages daily and version updates for GitHub Actions weekly. Routine npm version bumps are done by maintainers in batches. GitHub Actions are pinned to a commit SHA with the version in a trailing comment; keep that format when adding or updating an action.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is that a dev workflow or just re-hashing info here since it seemed related?

- **Dev dependencies** follow the same license rules and are otherwise at the maintainers' discretion.

## Security

Never report a vulnerability in a public issue, discussion or pull request. Use [private vulnerability reporting](https://github.com/IgniteUI/igniteui-webcomponents/security/advisories/new) as described in [SECURITY.md](../SECURITY.md).

When you contribute code, keep the following in mind:

- Treat every value that reaches a component from the host page as untrusted. Render text as text; when a feature must render HTML, sanitize it and make the sanitizer replaceable, as the chat markdown renderer does.
- Do not add network requests, storage access or telemetry. The library's [privacy commitments](../PRIVACY.md) depend on this.
- Do not introduce `eval`, `new Function`, string-based timers or other string-to-code paths.
- Changes to the workflows under `.github/workflows` or to the scripts that build and publish the package are reviewed for supply-chain impact. Keep job permissions minimal and actions pinned.

## Contributing Code

Expand Down
11 changes: 11 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
blank_issues_enabled: false
contact_links:
- name: 💬 Ask a question
url: https://github.com/IgniteUI/igniteui-webcomponents/discussions
about: Questions, ideas and general discussion belong in GitHub Discussions.
- name: 🗨️ Discord community
url: https://discord.gg/39MjrTRqds
about: Chat with other users and the team.
- name: 🏢 Infragistics support
url: https://www.infragistics.com/about-us/contact-us
about: Support for commercial Ignite UI products such as the Grids and Dock Manager.
17 changes: 17 additions & 0 deletions .github/SUPPORT.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# Support

Where to go depending on what you need:

| I want to... | Go to |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Read the documentation | [Product documentation](https://www.infragistics.com/products/ignite-ui-web-components) and [Storybook](https://igniteui.github.io/igniteui-webcomponents) |
| Report a bug or an accessibility problem | [Bug report](https://github.com/IgniteUI/igniteui-webcomponents/issues/new?template=bug_report.yaml). For accessibility, see [ACCESSIBILITY.md](../ACCESSIBILITY.md). |
| Request a component or feature | [Component request](https://github.com/IgniteUI/igniteui-webcomponents/issues/new?template=component.md) |
| Ask a question or share an idea | [GitHub Discussions](https://github.com/IgniteUI/igniteui-webcomponents/discussions) |
| Chat with the community | [Discord](https://discord.gg/39MjrTRqds) |
| Report a security vulnerability | [Private vulnerability reporting](https://github.com/IgniteUI/igniteui-webcomponents/security/advisories/new). See [SECURITY.md](../SECURITY.md). Never open a public issue for this. |
| Get help with a commercial Ignite UI product | [Infragistics support](https://www.infragistics.com/about-us/contact-us) |

Before opening an issue, search the existing [issues](https://github.com/IgniteUI/igniteui-webcomponents/issues) and [discussions](https://github.com/IgniteUI/igniteui-webcomponents/discussions). A bug report with a minimal reproduction, for example on StackBlitz, is resolved much faster than one without.

Only the [latest major version](../SECURITY.md#supported-versions) receives new fixes; the previous major receives critical security fixes only.
2 changes: 2 additions & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,4 +31,6 @@ Closes #
- [ ] My code follows the project's coding standards
- [ ] I have tested my changes locally
- [ ] I have updated documentation if needed
- [ ] I have added a `CHANGELOG.md` entry under `[Unreleased]`
- [ ] Breaking changes are documented in the description
- [ ] I have read the [contributing guidelines](https://github.com/IgniteUI/igniteui-webcomponents/blob/master/.github/CONTRIBUTING.md), including the accessibility, dependency and security rules
6 changes: 3 additions & 3 deletions .github/workflows/gh-pages-deploy.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,14 +19,14 @@ jobs:
url: ${{ steps.build-publish.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7.0.1
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-node@v7
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
with:
node-version: '24'
- id: build-publish
uses: bitovi/github-actions-storybook-to-github-pages@v1.0.4
uses: bitovi/github-actions-storybook-to-github-pages@ddd9d35f670cceedd2bfc444be681001b0709730 # v1.0.4
with:
path: storybook-static
install_command: npm ci
Expand Down
12 changes: 6 additions & 6 deletions .github/workflows/node.js.yml
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,8 @@ jobs:
runs-on: ubuntu-latest

steps:
- uses: actions/checkout@v7.0.1
- uses: actions/setup-node@v7
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
with:
node-version: '24'
cache: 'npm'
Expand All @@ -48,9 +48,9 @@ jobs:
# See supported Node.js release schedule at https://nodejs.org/en/about/releases/

steps:
- uses: actions/checkout@v7.0.1
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v7
uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
with:
node-version: ${{ matrix.node-version }}
cache: 'npm'
Expand All @@ -62,7 +62,7 @@ jobs:

- name: Restore the Playwright browsers
id: playwright-cache
uses: actions/cache@v6
uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
with:
path: ~/.cache/ms-playwright
key: playwright-${{ runner.os }}-${{ steps.playwright.outputs.version }}
Expand All @@ -81,7 +81,7 @@ jobs:

- name: Publish to coveralls.io
if: matrix.node-version == '24.x'
uses: coverallsapp/github-action@v2
uses: coverallsapp/github-action@8d6379e14d29928660c4ba802d8e85393440b329 # v2.3.8
with:
github-token: ${{ github.token }}
fail-on-error: false
56 changes: 56 additions & 0 deletions .github/workflows/scorecard.yml

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need to test this one out, however alt suggestion since @turbobobbytraykov already established a similar check in IgniteUI/igniteui-blazor#371 using actions/dependency-review-action

     - name: Review dependency changes
        uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0

https://github.com/IgniteUI/igniteui-blazor/blob/caee9f6c7f93d48a9a4b9b003b1fc3d37a9a71ff/.github/workflows/ci.yml#L29-L30

Producing

Image https://github.com/IgniteUI/igniteui-blazor/actions/runs/35250925962 as an example.

Again, all with the goal of consistency across the repos :)

Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# OpenSSF Scorecard: checks the repository's supply-chain posture (pinned
# dependencies, token permissions, branch protection, code review, and so on)
# and publishes the result to the Scorecard API, which powers the README badge.
#
# The publishing API rejects results from workflows that do not follow its
# rules: no workflow-level env or write permissions, and only the allow-listed
# actions in this job. Keep it as it is.
# https://github.com/ossf/scorecard-action#workflow-restrictions
name: OpenSSF Scorecard

permissions: read-all

on:
push:
branches: [master]
# Branch-protection settings change outside of pushes.
branch_protection_rule:
schedule:
# Saturdays at 01:30 UTC.
- cron: '30 1 * * 6'

jobs:
analysis:
name: Scorecard analysis
runs-on: ubuntu-latest
timeout-minutes: 15
permissions:
# Upload the SARIF to code scanning.
security-events: write
# OIDC token for publish_results.
id-token: write
Comment thread
rkaraivanov marked this conversation as resolved.

steps:
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

- name: Run analysis
uses: ossf/scorecard-action@2d1146689b8cda280b9bc96326124645441f03bc # v2.4.4
with:
results_file: results.sarif
results_format: sarif
publish_results: true

- name: Upload SARIF artifact
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
with:
name: scorecard-sarif
path: results.sarif
retention-days: 5

- name: Upload to code scanning
uses: github/codeql-action/upload-sarif@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0
with:
sarif_file: results.sarif
Loading
Loading