### Install web-features Package Source: https://github.com/web-platform-dx/web-features/blob/main/packages/web-features/README.md Installs the 'web-features' package using npm. This is the first step to using the package in a Node.js environment. ```sh npm install web-features ``` -------------------------------- ### Get Stats for Previous Release Source: https://github.com/web-platform-dx/web-features/blob/main/docs/publishing.md Fetches the previous release tag, checks out the corresponding commit, installs dependencies, and runs a script to gather statistics for the previous release. ```sh PREVIOUS_RELEASE_TAG=$(gh release view --json tagName --jq .tagName) git fetch --tags && git checkout "$PREVIOUS_RELEASE_TAG" && npm install && npx tsx ./scripts/stats.ts ``` -------------------------------- ### Install @next Release (npm) Source: https://github.com/web-platform-dx/web-features/blob/main/docs/publishing.md Installs the pre-release version of the web-features package using the `next` npm distribution tag. This command is useful for testing the latest development version. ```bash npm install web-features@next ``` -------------------------------- ### Set Up Local Environment for Web Features Source: https://github.com/web-platform-dx/web-features/blob/main/docs/CONTRIBUTING.md Commands to clone the repository, install dependencies, and create a new branch for development. Requires Node.js and Git. ```bash cd path/to/web-features npm install git checkout -b ``` -------------------------------- ### Get Stats for Main Branch Source: https://github.com/web-platform-dx/web-features/blob/main/docs/publishing.md Fetches the latest changes from the main branch, checks out the main branch, installs dependencies, and runs a script to gather statistics for the current main branch. ```sh git fetch origin main && git checkout origin/main && npm install && npx tsx ./scripts/stats.ts ``` -------------------------------- ### Feature File Example (YAML) Source: https://github.com/web-platform-dx/web-features/blob/main/docs/CONTRIBUTING.md This snippet demonstrates the structure and content of a YAML file used to define a feature within the web-features repository. It includes metadata such as name, description, specification, and support data. ```yaml # Example feature file content (conceptual) name: "Fetch API" description: "A modern interface for making network requests." specification: "https://fetch.spec.whatwg.org/" support_data: chrome: "42" firefox: "39" safari: "10.1" ``` -------------------------------- ### Listing Keys in web-features Source YAML - Example Scenario Source: https://github.com/web-platform-dx/web-features/blob/main/docs/bcd-sync.md Describes a scenario where BCD keys are initially unassigned and later mapped to features within the web-features repository. This involves a Dependabot upgrade, running a workflow to draft new features, and manual assignment by web-features maintainers. ```text 1. A new key appears in BCD (e.g., via a [Collector](https://github.com/openwebdocs/mdn-bcd-collector PR). 2. The author of the BCD PR doesn't know or doesn't care which feature that key belongs to and does not tag it. 3. A few days later, that data is released by BCD. That triggers the next `@mdn/browser-compat-data` Dependabot upgrade PR in the web-features repository. 4. After the Dependabot PR merges, we run the "Update draft features" workflow, which makes the new keys appear in the `features/draft` folder. 5. At this point, a web-features maintainer can assign the key to an existing feature or author a new feature. 6. A few days later, that data is released by web-features. When BCD upgrades `web-features`, it'll automatically add/remove tags to/from each key according to the `compat_features` list. ``` -------------------------------- ### Tagging BCD Keys - Example Scenario Source: https://github.com/web-platform-dx/web-features/blob/main/docs/bcd-sync.md Illustrates a typical workflow for tagging BCD keys, where a new or renamed key in BCD is associated with a web-feature using a `web-features:*` tag. This process is often initiated by a Collector PR and later reflected in web-features via Dependabot upgrades. ```text 1. A new key appears in BCD (e.g., via a [Collector](https://github.com/openwebdocs/mdn-bcd-collector) PR). 2. The author of the BCD PR knows which feature the key belongs to (e.g., due to a key being renamed) and tags the key with the correct `web-features:*` tag. 3. A few days later, that data is released by BCD. That triggers the next `@mdn/browser-compat-data` Dependabot upgrade PR in the web-features repository, where we regenerate web-features data based on the updated tag and automatically remove the redundant `compat_features` list from the source YAML file (if the list and tagged keys match). ``` -------------------------------- ### Avoiding Non-Literal Code Examples Source: https://github.com/web-platform-dx/web-features/blob/main/docs/guidelines.md Avoid using non-literal or idiosyncratic example code in descriptions. Stick to actual, commonly used code snippets that developers would recognize and use. ```Markdown The `some-prop` CSS property… ``` ```Markdown The `filter()` method returns the items… ``` -------------------------------- ### YAML: @counter-style Feature with BCD Keys Source: https://github.com/web-platform-dx/web-features/blob/main/docs/CONTRIBUTING.md Example of a feature file (YAML) for '@counter-style' that explicitly lists associated BCD keys under the `compat_features` field. This is used when BCD does not automatically reference the new feature. ```yaml name: "@counter-style" description: The `@counter-style` CSS at-rule defines custom counter styles for list items. For example, you can use a sequence of specific symbols instead of numbers for an ordered list. spec: https://drafts.csswg.org/css-counter-styles-3/ caniuse: css-at-counter-style compat_features: - css.at-rules.counter-style - css.at-rules.counter-style.additive-symbols - css.at-rules.counter-style.fallback - css.at-rules.counter-style.negative ``` -------------------------------- ### Get Can I Use Feature IDs with tsx Source: https://github.com/web-platform-dx/web-features/blob/main/docs/guidelines.md This command retrieves a comprehensive list of Can I Use feature IDs using Node.js and tsx. It's useful for understanding the available feature identifiers for linking with web features. ```bash npx tsx ./scripts/caniuse.ts ``` -------------------------------- ### Feature Identifier Naming Convention Source: https://github.com/web-platform-dx/web-features/blob/main/docs/guidelines.md Defines the naming convention for feature identifiers, requiring them to start with a lowercase letter and contain only lowercase alphanumeric characters and hyphens. ```YAML feature-identifier: startsWith: lowercase-alphabetic allowedChars: lowercase-alphanumeric, hyphen separator: hyphen ``` -------------------------------- ### YAML: Grid Feature without BCD Keys Source: https://github.com/web-platform-dx/web-features/blob/main/docs/CONTRIBUTING.md Example of a feature file (YAML) for 'Grid' that does not explicitly list BCD keys, relying on BCD's existing mappings. This indicates that the BCD project already associates the correct BCD keys with the 'grid' web-features ID. ```yaml name: Grid description: CSS Grid is a two-dimensional layout system, which lays content out in rows and columns. spec: https://drafts.csswg.org/css-grid-3/ group: grid caniuse: css-grid ``` -------------------------------- ### Compute Baseline Status for Multiple Compat Keys using computeBaseline Source: https://github.com/web-platform-dx/web-features/blob/main/packages/compute-baseline/README.md Calculates the Baseline status for a group of compatibility keys. Note that the support data returned by this method has not undergone editorial review and should not be used for presenting official Baseline statuses. The `toJSON()` method can be used to get a plain JSON representation. ```javascript import { computeBaseline } from "compute-baseline"; computeBaseline({ compatKeys: [ "javascript.builtins.AsyncFunction", "javascript.builtins.AsyncFunction.AsyncFunction", "javascript.operators.async_function", "javascript.operators.await", "javascript.statements.async_function", ], }); /* Returns: { baseline: 'high', baseline_low_date: '2017-04-05', baseline_high_date: '2019-10-05', discouraged: false, support: Map(7) { … }, toJSON: [Function: toJSON] } */ ``` -------------------------------- ### Instantiate AudioContext (JavaScript) Source: https://github.com/web-platform-dx/web-features/blob/main/docs/CONTRIBUTING.md This JavaScript code snippet demonstrates how to instantiate the AudioContext interface, which serves as an entry point for the Web Audio API feature. ```javascript const audioContext = new AudioContext() ``` -------------------------------- ### Browserslist Configuration for Baseline Source: https://github.com/web-platform-dx/web-features/blob/main/gh-pages/src/baseline-in-the-wild.md This snippet details how to use a `browserslist-config-baseline` module to configure targets for the browserslist tool. It involves adding a configuration to the `package.json` file, which is typically in JSON format. ```JSON { "browserslist": "extends browserslist-config-baseline" } ``` -------------------------------- ### Compute Baseline with Custom Data (JavaScript) Source: https://github.com/web-platform-dx/web-features/blob/main/packages/compute-baseline/README.md This snippet demonstrates how to use the compute-baseline library with custom compatibility data. It imports necessary modules, initializes the Compat class with provided data, and then computes baseline data for specified compat keys. ```javascript import data from "some-parsed-json-file"; import { computeBaseline } from "compute-baseline"; import { Compat } from "compute-baseline/browser-compat-data"; const compat = new Compat(data); computeBaseline( { compatKeys: ["css.properties.border-color"], }, compat, ); ``` -------------------------------- ### Get Baseline Status for a Feature Entry using getStatus Source: https://github.com/web-platform-dx/web-features/blob/main/packages/compute-baseline/README.md Retrieves the Baseline status for a specific browser compatibility data entry within a web feature. This function is intended for use with features that have completed the full Baseline editorial review process. ```javascript import { getStatus } from "compute-baseline"; getStatus("fetch", "api.Response.json"); /* Returns: { baseline: 'high', baseline_low_date: '2017-03-27', baseline_high_date: '2019-09-27', support: { chrome: '42', chrome_android: '42', edge: '14', firefox: '39', firefox_android: '39', safari: '10.1', safari_ios: '10.3' } } */ ``` -------------------------------- ### Download Baseline Newly Available Logo Assets Source: https://github.com/web-platform-dx/web-features/blob/main/gh-pages/src/name-and-logo-usage-guidelines.md Provides links to download the Baseline Newly Available logo assets in PNG and SVG formats, for both light and dark backgrounds. These are used to indicate a web platform feature has a 'baseline': 'low' value. ```HTML
Baseline newly available icon
Download PNG | Download SVG 		Baseline newly available icon dark
Download PNG | Download SVG
Baseline newly available wordmark
Download PNG | Download SVG 		Baseline newly available wordmark dark
Download PNG | Download SVG
``` -------------------------------- ### Download Baseline Wordmark Assets Source: https://github.com/web-platform-dx/web-features/blob/main/gh-pages/src/name-and-logo-usage-guidelines.md Provides links to download the Baseline wordmark in PNG and SVG formats, including versions for both light and dark backgrounds. These are used when referring to 'Baseline' as a concept. ```HTML
Baseline wordmark
Download PNG | Download SVG 		Baseline wordmark dark
Download PNG | Download SVG
``` -------------------------------- ### Download Baseline Widely Available Logo Assets Source: https://github.com/web-platform-dx/web-features/blob/main/gh-pages/src/name-and-logo-usage-guidelines.md Provides links to download the Baseline Widely Available logo assets in PNG and SVG formats, for both light and dark backgrounds. These are used to indicate a web platform feature has a 'baseline': 'high' value. ```HTML
Baseline widely available icon
Download PNG | Download SVG 		Baseline widely available icon dark
Download PNG | Download SVG
Baseline widely available wordmark
Download PNG | Download SVG 		Baseline widely available wordmark dark
Download PNG | Download SVG
``` -------------------------------- ### Initialize and Update UI based on URL Parameters Source: https://github.com/web-platform-dx/web-features/blob/main/gh-pages/src/supported-browsers.html This JavaScript code initializes the application by reading URL parameters to determine settings like 'includeDownstream' and 'targetYear'. It then updates the UI elements and fetches compatible browser versions accordingly. Event listeners are set up to handle user interactions with checkboxes and select elements, updating the URL and UI as needed. ```JavaScript const includeDownstreamFromUrl = urlParams.get("includeDownstream") === "true" ? true : false; showHideElements("downstreamContainer", includeDownstreamFromUrl); setInputValue( document.getElementById("downstreamBrowsersCheckbox"), includeDownstreamFromUrl, ); // Look for target year in URL if (urlParams.get("targetYear")) { configObject.targetYear = parseInt(urlParams.get("targetYear")); setInputValue(targetSelect, configObject.targetYear); } // Look for WA date in URL else if (urlParams.get("widelyAvailableOnDate")) { configObject.widelyAvailableOnDate = urlParams.get("widelyAvailableOnDate"); setInputValue(datePicker, configObject.widelyAvailableOnDate); setInputValue(targetSelect, "widelyAvailableOnDate"); showHideElements("widelyAvailableOnDateLabel", true); } // Look for newly available in URL else if (urlParams.get("target")) { if (urlParams.get("target") === "newlyAvailable") { setInputValue(targetSelect, "newlyAvailable"); configObject.widelyAvailableOnDate = maxWaDate; } } try { insertVersions(configObject); } catch (error) { console.error("Error fetching compatible versions:", error); document.getElementById("supportedVersionsList").innerHTML = `
  • Error fetching compatible browsers.
  • ${error.message}
    • `; } // Event handlers for inputs document .getElementById("downstreamBrowsersCheckbox") .addEventListener("change", (e) => { updateUrl(urlParams, { set: { includeDownstream: e.target.checked }, }); showHideElements("downstreamContainer", e.target.checked); return; }); document.getElementById("targetSelect").addEventListener("change", (e) => { e.preventDefault(); const target = e.target.value; if (target == "widelyAvailable" || target == "newlyAvailable") { if (target == "newlyAvailable") insertVersions({ widelyAvailableOnDate: maxWaDate }); else insertVersions(); showHideElements("widelyAvailableOnDateLabel", false); updateUrl(urlParams, { set: { target: target }, delete: ["widelyAvailableOnDate", "targetYear"], }); return; } if (target == "widelyAvailableOnDate") { insertVersions({ widelyAvailableOnDate: document.getElementById("widelyAvailableOnDatePicker").value, }); showHideElements("widelyAvailableOnDateLabel", true); updateUrl(urlParams, { set: { widelyAvailableOnDate: datePicker.value }, delete: ["target", "targetYear"], }); return; } insertVersions({ targetYear: target }); updateUrl(urlParams, { set: { targetYear: target }, delete: ["target", "widelyAvailableOnDate"], }); showHideElements("widelyAvailableOnDateLabel", false); return; }); document .getElementById("widelyAvailableOnDatePicker") .addEventListener("change", (e) => { insertVersions({ widelyAvailableOnDate: e.target.value }); urlParams.set("widelyAvailableOnDate", e.target.value); history.replaceState(null, null, "?" + urlParams.toString()); }); // Call init function init(); ``` -------------------------------- ### Initialize Page Elements and Data (JavaScript) Source: https://github.com/web-platform-dx/web-features/blob/main/gh-pages/src/supported-browsers.html This JavaScript function initializes the page by populating a year dropdown, setting the maximum date for a date picker, and preparing the UI for displaying browser compatibility information. ```JavaScript const init = () => { const configObject = {}; const yearArray = [...Array(nextYear).keys()].slice(2015).reverse(); yearArray.forEach((year) => { let newElement = document.createElement("option"); setInputValue(newElement, year); newElement.innerText = year; document.getElementById("targetSelect").appendChild(newElement); }); setInputValue(datePicker, new Date().toISOString().slice(0, 10)); datePicker.setAttribute("max", maxWaDate.toISOString().slice(0, 10)); // Set downstream browser display // NB: downstream browsers are always ``` -------------------------------- ### HTML datalist Element Support Source: https://github.com/web-platform-dx/web-features/blob/main/towards-features.md This snippet represents the documentation for the HTML `` element. It aggregates information from various sources to provide a consolidated view of its meaning and implementation status across different browsers. ```HTML ``` -------------------------------- ### Format Code with Prettier Source: https://github.com/web-platform-dx/web-features/blob/main/docs/CONTRIBUTING.md Instructions on how to enable automatic code formatting using Prettier in your editor for consistent code style. ```javascript // Enable Prettier in your editor for automatic code formatting. ``` -------------------------------- ### Create New Feature YAML File Source: https://github.com/web-platform-dx/web-features/blob/main/docs/CONTRIBUTING.md Defines the minimum required content for a new feature YAML file, including name, description, and specification URL. Uses YAML format. ```yaml name: "My feature" description: "A short description of the feature." spec: https://urlofthespec.com ``` -------------------------------- ### Commit and Push Changes (Git) Source: https://github.com/web-platform-dx/web-features/blob/main/docs/CONTRIBUTING.md These Git commands are used to commit local changes and push them to a remote repository, typically for a feature branch, in preparation for a pull request. ```bash git commit -a -m "Description of your changes" git push origin ``` -------------------------------- ### Generate Dist Files with npm Source: https://github.com/web-platform-dx/web-features/blob/main/docs/CONTRIBUTING.md This command is used to generate distribution files (.yml.dist) from authored YAML files. These dist files are crucial for build processes and contain compatibility data and status information. ```bash npm run dist ``` -------------------------------- ### Bash: Distribute and Traverse BCD Source: https://github.com/web-platform-dx/web-features/blob/main/docs/CONTRIBUTING.md Shell commands for interacting with the browser-compat-data (BCD) project. `npm run dist` is used to check for supported browser versions after preparing a feature file, and `npm run traverse | grep -i ` helps find BCD keys matching a specific keyword. ```bash npm run dist ``` ```bash npm run traverse | grep -i ``` -------------------------------- ### BCD Keys in compat_features - web-features Source: https://github.com/web-platform-dx/web-features/blob/main/docs/bcd-sync.md Demonstrates how Browser Compatibility Data (BCD) entry keys are represented within the `compat_features` field in web-features source YAML files. This field can be directly defined or automatically populated based on BCD tags. ```yaml compat_features: - css.properties.background-color ``` -------------------------------- ### Generate Feature Dist File (npm) Source: https://github.com/web-platform-dx/web-features/blob/main/docs/CONTRIBUTING.md This command generates or regenerates the distribution file for a specific feature. It's used to create a .yml.dist file based on associated BCD keys. ```bash npm run dist npm run dist -- features/.yml ``` -------------------------------- ### Import Data from web-features (Browser) Source: https://github.com/web-platform-dx/web-features/blob/main/packages/web-features/README.md Imports the 'data.json' file from the 'web-features' package directly in a browser environment using dynamic import with JSON type assertion. This allows access to browsers, features, groups, and snapshots without a Node.js build process. ```javascript import data from "web-features/data.json" with { type: "json" }; const { browsers, features, groups, snapshots } = data; ``` -------------------------------- ### Import Data from web-features (Node.js) Source: https://github.com/web-platform-dx/web-features/blob/main/packages/web-features/README.md Imports core data structures like browsers, features, groups, and snapshots from the 'web-features' package using ES module syntax in a Node.js environment. ```javascript import { browsers, features, groups, snapshots } from "web-features"; ``` -------------------------------- ### Load Browser Compatibility Data (JavaScript) Source: https://github.com/web-platform-dx/web-features/blob/main/gh-pages/src/supported-browsers.html This JavaScript code attempts to load the `getCompatibleVersions` function from a CDN. If the first attempt fails, it falls back to another CDN. If both fail, it displays an error message to the user. ```JavaScript let getCompatibleVersions; try { getCompatibleVersions = await import( "https://cdn.jsdelivr.net/npm/baseline-browser-mapping" ).then((response) => response.getCompatibleVersions); } catch { console.log( "Loading baseline-browser-mapping from cdn.jsdelivr.net failed, attempting to load from unpkg.com.", ); try { getCompatibleVersions = await import( "https://unpkg.com/baseline-browser-mapping" ).then((response) => response.getCompatibleVersions); } catch { document.getElementById("loadingContainer").innerText = "There was an error loading baseline-browser-mapping which is required for this page to work. Please check your network connection and refresh the page."; throw new Error( "There was an error loading baseline-browser-mapping which is required for this page to work. Please check your network connection and refresh the page.", ); } } ``` -------------------------------- ### Include Baseline Status Web Component Source: https://github.com/web-platform-dx/web-features/blob/main/gh-pages/src/use-baseline.md This snippet shows how to include the `` web component on your website to display the current status of a web feature. This component dynamically renders the latest Baseline status, ensuring up-to-date information for your audience. ```HTML ``` -------------------------------- ### Web Component for Displaying Baseline Status Source: https://github.com/web-platform-dx/web-features/blob/main/gh-pages/src/baseline-in-the-wild.md This snippet describes a custom web component designed to display Baseline status on a website. It would typically be implemented using HTML, CSS, and JavaScript. ```HTML ``` ```JavaScript /* Example JavaScript for the web component (conceptual) */ class BaselineStatus extends HTMLElement { constructor() { super(); // attach shadow DOM, set up properties, etc. } connectedCallback() { // render the component based on attributes this.render(); } static get observedAttributes() { return ['feature', 'year']; } attributeChangedCallback(name, oldValue, newValue) { if (name === 'feature' || name === 'year') { this.render(); } } render() { const feature = this.getAttribute('feature'); const year = this.getAttribute('year'); this.innerHTML = `Status for ${feature} in ${year}: [Data Placeholder]`; } } customElements.define('baseline-status', BaselineStatus); ``` ```CSS /* Example CSS for styling the web component */ baseline-status { display: inline-block; padding: 5px; border: 1px solid #ccc; border-radius: 4px; font-family: sans-serif; } ``` -------------------------------- ### Set NPM_TOKEN Repository Secret (gh CLI) Source: https://github.com/web-platform-dx/web-features/blob/main/docs/publishing.md Sets the `NPM_TOKEN` secret for the web-platform-dx/web-features repository using the GitHub CLI. This token is required for publishing packages. ```bash gh secret set --repo=web-platform-dx/web-features NPM_TOKEN ```