diff --git a/.github/upload-staging.sh b/.github/upload-staging.sh index 246d4c3a96..3138902817 100755 --- a/.github/upload-staging.sh +++ b/.github/upload-staging.sh @@ -18,6 +18,19 @@ aws cloudfront create-invalidation --distribution-id EQE4NPRH0CQXJ --paths "/*" if [ -d "packages/site/dist" ]; then aws s3 rm --recursive s3://patternfly-org-preview + aws s3 sync packages/site/dist s3://patternfly-org-preview --exclude "*" \ + --include "*.html" \ + --include "*.json" \ + --exclude "static/**/*.json" \ + --include "sw.js" \ + --cache-control "public, max-age=0, must-revalidate" + aws s3 sync packages/site/dist s3://patternfly-org-preview --include "*" \ + --exclude "*.html" \ + --exclude "*.json" \ + --include "static/**/*.json" \ + --exclude "sw.js" \ --cache-control "public, max-age=31536000, immutable" + + aws cloudfront create-invalidation --distribution-id E2IXSH9IWFQCUC --paths "/*" fi diff --git a/.gitignore b/.gitignore index 794e0fd8d8..e1c51b2641 100644 --- a/.gitignore +++ b/.gitignore @@ -26,6 +26,8 @@ public static .cache /build +packages/site/src/generated +dist # IDE - VSCode .vscode diff --git a/lerna.json b/lerna.json index 318277420f..e48348b573 100644 --- a/lerna.json +++ b/lerna.json @@ -13,8 +13,10 @@ "packages": [ "packages/ast-helpers", "packages/documentation-framework", - "packages/documentation-site" + "packages/documentation-site", + "packages/site" ], "version": "independent", "allowBranch": ["main", "v4", "v5"] } +git \ No newline at end of file diff --git a/package.json b/package.json index eba8391344..08489a5fed 100644 --- a/package.json +++ b/package.json @@ -8,9 +8,10 @@ "scripts": { "analyze": "yarn workspace patternfly-org analyze", "develop": "yarn workspace patternfly-org develop", + "dev": "yarn workspace site dev", "develop:extensions": "EXTENSIONS_ONLY=true PRERELEASE=true yarn develop", "build:analyze": "yarn workspace patternfly-org build:analyze && yarn copy", - "build": "yarn workspace patternfly-org build && yarn copy", + "build": "yarn workspace patternfly-org build && yarn workspace site build && yarn copy", "build:extensions": "EXTENSIONS_ONLY=true PRERELEASE=true yarn build", "copy": "rm -rf build/patternfly-org/site && mkdir -p build/patternfly-org && cp -r packages/documentation-site/public build/patternfly-org/site", "clean": "lerna run clean && rm -rf build", diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/_template.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/_template.md deleted file mode 100644 index 57342c0142..0000000000 --- a/packages/documentation-site/patternfly-docs/content/design-guidelines/_template.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -id: -section: components ---- - -We’re working on some guidelines for this component. -If you have any questions in the meantime, feel free to [get in touch with us.](/community#get-in-touch) diff --git a/packages/site/README.md b/packages/site/README.md new file mode 100644 index 0000000000..b9ede4b9e8 --- /dev/null +++ b/packages/site/README.md @@ -0,0 +1 @@ +# Patternfly site built with doc core diff --git a/packages/site/package.json b/packages/site/package.json new file mode 100644 index 0000000000..53871fd7cd --- /dev/null +++ b/packages/site/package.json @@ -0,0 +1,21 @@ +{ + "name": "site", + "type": "module", + "version": "0.0.1", + "scripts": { + "clean": "rm -rf src/generated", + "generate:content": "patternfly-doc-core convert-to-mdx ../documentation-site/patternfly-docs/content/", + "dev": "patternfly-doc-core start", + "build": "patternfly-doc-core build", + "serve": "patternfly-doc-core serve", + "sync": "patternfly-doc-core sync", + "init:docs": "patternfly-doc-core init" + }, + "dependencies": { + "@patternfly/patternfly-doc-core": "^1.9.0", + "astro": "^5.7.13" + }, + "devDependencies": { + "tsx": "^4.19.0" + } +} diff --git a/packages/site/pf-docs.config.mjs b/packages/site/pf-docs.config.mjs new file mode 100644 index 0000000000..4e6576da21 --- /dev/null +++ b/packages/site/pf-docs.config.mjs @@ -0,0 +1,32 @@ +export const config = { + content: [ + // example content entry for local content, this would feed all markdown files in the content directory to the + // documentation core with a content identifier of 'content': + { + base: 'src/', + pattern: "**/*.{md,mdx}", + name: 'content' + }, + // + // example content entry for remote content, this would fetch all markdown files matching the glob in 'pattern' + // from the specified npm package and serve them with a content identifier of 'react-component-docs': + // { + // packageName: "@patternfly/react-core", + // pattern: "**/components/**/*.md", + // name: "react-component-docs", + // }, + ], + navSectionOrder: [], + outputDir: './dist', + propsGlobs: [ + // { + // include: ['*/@patternfly/react-core/src/**/*.tsx'], + // exclude: [ + // '/**/examples/**', + // '/**/__mocks__/**', + // '/**/__tests__/**', + // '/**/*.test.tsx', + // ], + // }, + ], +} diff --git a/packages/site/rename-md-to-mdx.sh b/packages/site/rename-md-to-mdx.sh new file mode 100755 index 0000000000..6548ac2bcf --- /dev/null +++ b/packages/site/rename-md-to-mdx.sh @@ -0,0 +1,15 @@ +#!/bin/bash + +# Find all .md files in the src directory and its subdirectories +find src -name "*.md" | while read -r file; do + # Create the new filename by replacing .md with .mdx + new_file="${file%.md}.mdx" + + # Only rename if the file exists and hasn't been renamed already + if [ -f "$file" ] && [ ! -f "$new_file" ]; then + echo "Renaming: $file -> $new_file" + mv "$file" "$new_file" + fi +done + +echo "Renaming complete!" \ No newline at end of file diff --git a/packages/site/src/content/get-started/about-patternfly.mdx b/packages/site/src/content/get-started/about-patternfly.mdx new file mode 100644 index 0000000000..4d410284b7 --- /dev/null +++ b/packages/site/src/content/get-started/about-patternfly.mdx @@ -0,0 +1,335 @@ +--- +id: About PatternFly +title: About PatternFly +section: get-started +--- + +import './get-started.css'; +import { Button, Card, CardHeader, CardTitle, CardBody, CardFooter, Divider, Icon, Grid, GridItem, PageSection, Split, SplitItem, Title, Tooltip } from '@patternfly/react-core'; +import ExternalLinkAltIcon from '@patternfly/react-icons/dist/esm/icons/external-link-alt-icon'; + +## What is PatternFly? + +PatternFly is an open source design system that enables designers and developers to create consistent and usable software products. + +A **design system** is a collection of software design standards and resources that facilitate more consistent and productive design processes. When you design and develop with a design system, you can reduce redundancy and enable a unified language between cross-functional teams. This means that products will be visually consistent, and will use patterns that support better usability and efficiency. + +The PatternFly design system is created and maintained by Red Hat, and is used across Red Hat's product catalog, but it's open for anyone to use. Across our website, we provide code samples, clear standards, and additional resources to help designers and developers work together more efficiently. Together, we can build better user experiences. + +## What does PatternFly include? + +### Foundations + +PatternFly's foundations create a strong base for the rest of the design system to be built with. + + + + + + **Design foundations** + + The most foundational elements of our design system, like color, typography, icons, and spacing. + + + + + + + **Design tokens** + + Semantically named variables that represent visual attributes and design styles. + + + + +### Elements + +PatternFly’s core elements are what you will work directly with when building a UI. + + + + + + **Components** + + Flexible, modular, building blocks that you can mix and match to create UIs. + + + + + + + **Layouts** + + Different methods for arranging components for different screen sizes and content presentations. + + + + + + + **Charts** + + Different methods to present data visualizations. + + + + + + + **Extensions** + + Reusable solutions that utilize multiple PatternFly components for cross-project use cases. + + + + +### Guidance + +We provide extensive guidelines to help you create UIs following best practices. + + + + + + **Patterns** + + Recommendations and solutions for common design problems that involve multiple components. + + + + + + + **Accessibility** + + Guidelines to follow in order to create products that are usable and accessible by all users. + + + + + + + **UX writing** + + Content guidelines that provide principles and best practices around writing for user experience. + + + + + +### Additional developer resources + +We offer more complex resources to assist with the development process. + + + + + + **Topology** + + A method for modeling the arrangement of elements in a network. + + + + + + + **Utility classes** + + Additional CSS classes that allow you to further customize and modify UI elements, like alignment, spacing, and shadows. + + + + + +## Join the community + +At the core of PatternFly is our global community of designers, developers, and other UX professionals with a passion for open source—in other words, our Flyers. Whether we're contributing to PatternFly or just staying up to date on new releases, we work together to make PatternFly a vibrant community of passionate people. Together, we celebrate creativity and foster a sense of teamwork and unity. + +The PatternFly community is never finished growing, and we want to keep it that way, so reach out whenever—we're always open. + + + + Chat with us + + We have a Slack workspace, where you can ask us questions and share any feedback. Just like PatternFly, our Slack channels are open for all and we encourage you to join to connect with the team. + + + + [Join our Slack workspace ](https://patternfly.slack.com/archives/C293LQ36J) + + + + Stay up to date + + Make sure you're in the loop on important updates and discussions by signing up for PatternFly emails. We can send meeting reminders, updates, and other important information right to your inbox. + + + + [Sign up for our mailing list ](https://www.redhat.com/dynamic-form/instance/934b1674-bc8a-4a13-8c9d-d19abcceb263) + + + + Join our meetings + + Flyers may be spread all over the globe, but we make sure to come together to share updates and collect feedback. If you can't make it, all meetings are recorded and published on our YouTube channel. + + + + [View our Google calendar ](https://calendar.google.com/calendar/embed?src=patternflyteam%40gmail.com&ctz=America%2FNew_York) + + + + Read our blog + + Our team is passionate, and we have a lot to say about open source and user experience—too much to fit on our website! Our Medium publication hosts articles about PatternFly projects, industry practices, professional experience, and more. + + + + [Visit our Medium publication ](https://medium.com/patternfly) + + + + Follow us on X + + If you want to keep up with us via social media, you can find us on X. We share meeting reminders, release announcements, community messages, and links to new Medium articles that you can add to your reading list. + + + + [Follow us on X ](https://x.com/patternfly) + + + + Request a new feature + + We welcome all ideas for adding or improving features! We review all requests, taking into account scope and technical constraints. Accepted requests are placed on [our feature roadmap](https://github.com/orgs/patternfly/projects/16/views/2), and we'll work with you to design and develop a solution. + + + + [Visit our GitHub discussions board ](https://github.com/orgs/patternfly/discussions/categories/feature-requests) + + + + +#### New communities +Sometimes Flyers branch out and build groups of their own, creating new communities. While these communities are separate from PatternFly and not supported as part of our design system, we still love seeing our Flyers turning their visions into actions. + +- **[PatternFly Elements](https://patternflyelements.org):** A community created by web-based developers at Red Hat, focused on creating web components for use across Red Hat's sites and SaaS products. It offers theming options for your own brand library. + +- **[PatternFly Kotlin](https://github.com/patternfly-kotlin/patternfly-kotlin):** A Kotlin implementation of PatternFly based on fritz2, targeting Kotlin/JS. The goal of this project is to provide all PatternFly components in Kotlin, matching the reactive nature of fritz2. The components use stores, handlers, and other elements from the fritz2 API. For a quick overview, [view the PatternFly Kotlin showcase.](https://patternfly-kotlin.github.io/patternfly-kotlin-showcase/#home) + +- **[Ansible Component Guide and Sketch Library](https://www.sketch.com/s/6ccbd710-267d-4b69-9dae-bc19e1551056):** An additional resource that designers can use that is built on top of existing PatternFly components. It is a rapid mockup prototyping tool that can be used to quickly put together repeatable design patterns and layouts across projects. This is specific to Ansible, but many of the components are generalized and can fit many product use cases. + +- **[PatternFly for Yew](https://github.com/patternfly-yew/patternfly-yew)**: Provides PatternFly components for Yew—a Rust based framework for creating web applications that can run in the browser using WASM. The project aims to create Yew components for all components and concepts found in PatternFly. For a quick demo and starter template, [see the PatternFly Yew Quickstart.](https://github.com/patternfly-yew/patternfly-yew-quickstart) + +## Where do I start? + +Now that you've been introduced to PatternFly, you're ready to start designing or start developing your product. Looking to get involved in the behind-the-scenes work? Check out our contribution guidelines for more instruction. + + + + + + + +## Release cadence + +### Major releases + +A major release is one that sees the version of PatternFly increase, for example PatternFly 5 to PatternFly 6. Major releases are the only releases with planned "breaking changes" that alter the way your product's code interacts with PatternFly's code. + +Along with each major release, we will provide detailed upgrade guides and codemods to support the work needed to upgrade your products to the latest version. + +A major version of PatternFly will only be supported through the subsequent version. This means, with the release of PatternFly 6, we no longer offer support PatternFly 4. + +### Minor and patch releases + +Minor feature releases will be available quarterly to introduce non-breaking changes, like new features and enhancements. We will also share interim patch releases to fix any bugs that we find. + +## Beta components + +New PatternFly components are first released in beta. To help you identify beta components, we add a blue label beside the component in the PatternFly.org navigation menu and an informational alert at the top of the component’s documentation pages. + +Beta components continue to evolve as users share feedback. As these components are tested, they are subject to breaking changes, which are changes that affect visuals, applied CSS class names, or existing React properties (including the addition of new properties). We review beta components every quarter to evaluate their stability and the degree to which they meet product requirements. Once a component is stable, it's proposed as a promotion candidate. Once promoted, breaking changes are not made to components outside of a well-advertised breaking change release. + +Occasionally, after a component is promoted out of beta, subsequent enhancement requests require the introduction of new CSS class names and React properties. Whenever these enhancements are substantial enough to lead to further component updates (pending testing and feedback), then a beta label is applied to the new class names and properties, as well as relevant examples in the component’s documentation. + +[Learn more about beta components and view a list of current promotion candidates here.](https://github.com/patternfly/patternfly-org/tree/main/beta-component-promotion) + +If you are considering using a beta component, make sure to: + +1. Play with the examples in the component's documentation on the PatternFly website to determine if the current implementation meets your needs. Open issues for any missing features, enhancement requests, or bugs. +2. Check the [PatternFly Issues GitHub Project board](https://github.com/orgs/patternfly/projects/7/views/1). Browse any open issues for the beta component to determine how much more the beta component could evolve in the near future. + +## Deprecated components + +Deprecated components are components that are no longer recommended for use in PatternFly, either due to significant design or code changes. Once deprecated, a component is replaced with a newer implementation, and the previous implementation is no longer maintained or enhanced. + +Occasionally, a component page will contain a "React next" tab, which contains details about planned changes for the implementation of the component. This updated implementation will be promoted to the main component page as part of a major release, and will become the new recommended implementation. When this happens, the previous implementation will be deprecated. Deprecated component implementations will remain available until a following major release, but will no longer be maintained or updated. + +Deprecated components will typically be available to use until the next major release, after which no documentation will be included on the current release website. + +![Onsite deprecated component messages](./img/deprecated-component.png) + +Deprecation includes: + +1. Components that are removed completely, in favor of a different component. + - The newly recommended component will be mentioned and linked on the deprecated component's page. +1. Components that still exist, but have significant implementation changes. + - The new implementation will populate the "React tab," while documentation for the deprecated implementation will be placed under a "React deprecated" tab. You will see an alert on both the React and React deprecated pages. diff --git a/packages/site/src/content/get-started/contribute.md b/packages/site/src/content/get-started/contribute.md new file mode 100644 index 0000000000..0a909b5964 --- /dev/null +++ b/packages/site/src/content/get-started/contribute.md @@ -0,0 +1,71 @@ +--- +id: Contribute +title: Contribute to PatternFly +section: get-started +--- + +## Community contributions + +Thank you for your interest in contributing to PatternFly! We depend on community contributions to help our design system grow and evolve. We encourage everyone, regardless of background, to get involved. Common contributions include (but aren't limited to): +- New feature ideas. +- Bug reports. +- Documentation updates. + +This guide outlines the ways that you can contribute to PatternFly's design, code, and documentation to help us stay on top of the latest and greatest solutions. + +If you have any ideas that don't fit into the projects outlined in this guide, please [reach out to us on Slack](https://patternfly.slack.com/archives/C293LQ36J). + +## Design + +If you have skills in visual and interaction design, you can contribute to PatternFly's design by taking an existing issue or proposing a new feature, enhancement, or icon. If you are interested in any of these projects, [reach out on the patternfly-design Slack channel.](http://join.slack.com/t/patternfly/shared_invite/zt-1npmqswgk-bF2R1E2rglV8jz5DNTezMQ) + +### Existing design issues + +The PatternFly design team is composed of visual and interaction designers who define the look and feel of the PatternFly library. The team follows an agile framework, planning their work in sprints, with a backlog that is tracked and managed via [this GitHub project board.](https://github.com/orgs/patternfly/projects/7/views/30) This board contains a list issues that are currently unassigned and waiting in the queue. If you see something here that you'd like to work on, leave a comment on the issue and a member of our team will reach out with next steps. + +### New feature or enhancement +If you have an idea for a new design pattern, a new component type, or an existing feature improvement, we'd love to hear it. [Start by opening an issue in the patternfly-design repository.](https://github.com/patternfly/patternfly-design/issues) From there, a member of our team will reach out and work with you to plan and design a solution. + +### New icons +We encourage designers to work with [the existing PatternFly icon set](/design-foundations/icons), which covers most common use cases. If your use case isn't covered, you can propose a new icon. + +To contribute a new icon, [start by opening an issue in the patternfly-design repository](https://github.com/patternfly/patternfly-design/issues) that describes your idea and why it's needed. A member of our team will reach out to you to discuss next steps. + +## Code + +The primary PatternFly libraries include HTML/CSS (commonly called "core") and React. If you're looking to contribute to PatternFly's codebase, these libraries are a good place to start. You can help out by taking existing issues, or creating issues for bugs and other changes. + +If you have any questions about these projects, you can reach out to us on our [patternfly-core](https://patternfly.slack.com/archives/C9Q224EFL) and [patternfly-react](https://patternfly.slack.com/archives/C4FM977N0) Slack channels. + +### Existing development issues + +To find work that has been approved, but not started, you can view open issues in our [patternfly](https://github.com/patternfly/patternfly/issues) (HTML/CSS) and [patternfly-react](https://github.com/patternfly/patternfly-react/issues) (React) repositories. If you find an issue that you'd like to work on, leave a comment and someone from our team will reach out to you with next steps. + +Be sure to view our detailed contribution instructions for both of these repositories: +- [Core contribution guidelines](https://github.com/patternfly/patternfly#guidelines-for-css-development) +- [React contribution guidelines](https://github.com/patternfly/patternfly-react/blob/main/CONTRIBUTING.md#contribution-process) + +### Bug reports + +If you believe that you've come across a PatternFly bug, alert our team, so that we can resolve the issue. To report a bug, follow these steps: + +1. View the documentation for the feature, to confirm that the behavior is not functioning as intended. +1. Search open issues in the [patternfly](https://github.com/patternfly/patternfly/issues) and [patternfly-react](https://github.com/patternfly/patternfly-react/issues) repositories to see if a related issue already exists. + - If the bug is present in only the React implementation of PatternFly, [create a bug issue in patternfly-react.](https://github.com/patternfly/patternfly-react/issues) + - If the bug can be seen on both the React and HTML/CSS side, [create a bug issue in patternfly](https://github.com/patternfly/patternfly/issues). +1. Be sure to mention which project the bug was noticed in and if there is a deadline that the fix is needed for. + +## Documentation + +Across our website, you can find PatternFly documentation that explains concepts, provides guidance, and outlines important resources for PatternFly users. Our documentation can always be improved, and we love to hear input from the people who use it. + +If you'd like to contribute to documentation, you can refer to our [detailed contribution instructions](https://github.com/patternfly/patternfly-org/wiki/Contributing-to-patternfly-org-for-designers) for additional guidance. + +### Existing documentation issues + +Our website documentation is contained in the [patternfly-org repository](https://github.com/patternfly/patternfly-org). If you find an issue that you'd like to work on, leave a comment and someone from our team will reach out to you with next steps. + +### Design guidelines +Our design guidelines are found across our component, layout, chart, and pattern web pages. These guides clarify usage details to help designers follow best practices to create strong UI solutions. + +If you'd like to contribute to our design guidelines, you can open an issue in [patternfly-org](https://github.com/patternfly/patternfly-org) to propose a new page or updates to an existing page. From there, our team will work with you to author and publish your new content. \ No newline at end of file diff --git a/packages/site/src/content/get-started/design-with-figma.mdx b/packages/site/src/content/get-started/design-with-figma.mdx new file mode 100755 index 0000000000..c9a6dbb254 --- /dev/null +++ b/packages/site/src/content/get-started/design-with-figma.mdx @@ -0,0 +1,79 @@ +--- +id: Design +title: Design with PatternFly +section: get-started +source: Design-with-Figma + +--- +import './get-started.css'; +import {Button, Divider} from '@patternfly/react-core'; +import ArrowRightIcon from '@patternfly/react-icons/dist/esm/icons/arrow-right-icon'; + + +## PatternFly 6 design kit + +To start designing with PatternFly, you will need to install our PatternFly 6 design kit. This kit gives you access to PatternFly's visual design system — including design tokens — so that you can create consistent and usable product experiences. + +
+ +
+ +In order to use PatternFly 6, your product *must* be using the PatternFly 6 design kit. If you haven't yet, you can [follow our upgrade guide](/get-started/upgrade) to complete your upgrade. Doing so also ensures that you'll have access to the most current PatternFly features, resources, and guidance going forward! + +If you have questions about the kit, or have trouble with installation, [refer to our help section](#get-help) or [reach out to us on Slack](http://join.slack.com/t/patternfly/shared_invite/zt-1npmqswgk-bF2R1E2rglV8jz5DNTezMQ). + +### PatternFly fonts + +To install the fonts that PatternFly uses, [download this GitHub repository](https://github.com/RedHatOfficial/RedHatFont) and install all files in the "TTF" folder. + +### Design tokens + +PatternFly 6 is built off of our new design token system. For more background and instructions regarding our token system, [check out our tokens documentation.](/tokens/about-tokens) + +## What's in the design kit? + +The PatternFly 6 design kit gives you access to: +- Our complete component library. +- Our design token system. +- Demos of full-screen designs. + +## Where do I start? + +After you install the PatternFly 6 Figma workspace, you will find a welcome page to help guide you through your first steps. Take time to read this information to familiarize yourself with our component library, contribution guidelines, and contact methods. + +Once you're familiar with the kit you're ready to start designing! + +If you're completely new to PatternFly, you should also first [read this overview of our design system](/get-started/about-patternfly), to learn about everything that PatternFly has to offer and get to know who we are. + +## How do I stay up to date? + +We plan to regularly release design kit updates to address any bugs and to evolve our design solutions. If you're a Red Hat employee, then you will automatically receive updates as they are released. If you are not a Red Hat employee, then you will have to manually check our Figma community page to find and install updates. [Read more about Figma access levels here.](#1.-how-do-i-get-figma-access) + + + +## Get help + +### 1. How do I get Figma access? + + - **Red Hat employees:** + + If you are a Red Hat employee on the User Experience Design (UXD) team, you will be added to the UXD workspace in Figma. This allows you to instantly receive library updates as they are made by the team. + + If you are a Red Hat employee, but you are not on the UXD team, you should work with your manager to be added to your team's respective workspace in Figma. + + - **PatternFly community members:** + + If you are not a Red Hat employee, you will need to create a copy of the [PatternFly 6 design file](https://www.figma.com/@patternfly) to install the library within your own Figma workspace. + + Note that you will not be able to receive automatic library updates since you are working from a local copy. The PatternFly team will release any updates every other week, as part of their sprint schedule. Be sure to revisit our Figma community page in order to download the latest updates. + +### 2. Can I still use Sketch? + +Before PatternFly 5, the PatternFly design kit was available within Sketch. We migrated our design system to Figma, with the release of [the PatternFly 5 library](https://www.figma.com/@patternfly). Sketch is no longer our recommendation, and the PatternFly 6 design kit is not available in Sketch. [See more details on the PatternFly 5 archive site.](https://v5-archive.patternfly.org/get-started/design#sketch-design-kit) + +### 3. How do I migrate to Figma? + +To migrate to Figma, just begin to create all new design work within Figma. If you have existing designs in another design tool that you want to bring into Figma, you will need to manually recreate each UI mockup using the PatternFly 5 or 6 component library. + +### 4. What if I haven't upgraded to PatternFly 6? +If your product hasn't been upgraded to PatternFly 6, you cannot use the PatternFly 6 design kit nor design tokens. Previous PatternFly libraries will no longer be maintained after the release of PatternFly 6. diff --git a/packages/site/src/content/get-started/develop.mdx b/packages/site/src/content/get-started/develop.mdx new file mode 100644 index 0000000000..3bced63390 --- /dev/null +++ b/packages/site/src/content/get-started/develop.mdx @@ -0,0 +1,181 @@ +--- +id: Develop +title: Develop with PatternFly +section: get-started +--- +import './get-started.css'; +import {Alert} from '@patternfly/react-core'; + +## Getting started + +In order to develop with PatternFly, you will need to: + +1. [Learn about the PatternFly design system](/get-started/about-patternfly) to get acquainted with all of its elements. + +1. [Learn about our design token system](/tokens/about-tokens), which enables you to build interfaces with consistent PatternFly styling, including colors, shadows, spacing, and more. + +1. Install a package manager to help you install, update, and configure all necessary PatternFly packages. We recommend [npm](https://nodejs.org/en/download) or [Yarn](https://yarnpkg.com/getting-started). + +1. Configure your environment to get started with our [React](#develop-with-react) and/or [HTML/CSS](#develop-with-htmlcss) libraries. + +## Develop with React + + +PatternFly supports the 2 most recent versions of React at a time. PatternFly 6 currently supports React 17 and 18, [with support for React 19 coming soon](https://github.com/orgs/patternfly/projects/16/views/23?pane=issue&itemId=83947829&issue=patternfly%7Cpf-roadmap%7C201). + + +[PatternFly's React library](https://github.com/patternfly/patternfly-react) contains a collection of components that you can use to build interfaces with consistent markup, styling, and behavior. It is composed of a number of React packages, which are published in the following npm packages: + +* [@patternfly/react-core](https://www.npmjs.com/package/@patternfly/react-core): Most React core components. +* [@patternfly/react-charts](https://www.npmjs.com/package/@patternfly/react-charts): PatternFly charting components. +* [@patternfly/react-code-editor](https://www.npmjs.com/package/@patternfly/react-code-editor): A PatternFly wrapper for the Monaco code editor. +* [@patternfly/react-icons](https://www.npmjs.com/package/@patternfly/react-icons): PatternFly icons as React components. +* [@patternfly/react-styles](https://www.npmjs.com/package/@patternfly/react-styles): CSS-in-JS capabilities. +* [@patternfly/react-table](https://www.npmjs.com/package/@patternfly/react-table): PatternFly table components. +* [@patternfly/react-tokens](https://www.npmjs.com/package/@patternfly/react-tokens): PatternFly's CSS variables, transformed into JavaScript objects for use with React. + +These packages are maintained together. To determine which versions of each package are compatible with the rest, view our [release highlights](https://www.patternfly.org/get-started/release-highlights). + +We support the following configurations: +* [TypeScript](https://github.com/patternfly/patternfly-react-seed/blob/master/tsconfig.json) +* [Webpack](https://github.com/patternfly/patternfly-react-seed/blob/master/webpack.common.js) +* [Jest](https://github.com/patternfly/patternfly-react-seed/blob/master/jest.config.js) +* [Editor](https://github.com/patternfly/patternfly-react-seed/blob/master/.editorconfig) + +### Install and configure PatternFly React + +#### New projects + +If you'd like to start using PatternFly via a sample project, you can use the [PatternFly React seed](https://github.com/patternfly/patternfly-react-seed). We created this open-source build scaffolding utility to help developers jump start new PatternFly projects. + +To get started: + +1. Fork the React seed: + - TypeScript: [Fork and clone the PatternFly React seed project](https://github.com/patternfly/patternfly-react-seed). + - JavaScript: [Fork and clone the JavaScript branch of the PatternFly React seed project](https://github.com/patternfly/patternfly-react-seed/tree/javascript). + + For more information about how to fork and clone a repo, [view GitHub Help](https://help.github.com/articles/fork-a-repo/). + +1. Install the project: + + Follow the steps outlined in the [React seed README](https://github.com/patternfly/patternfly-react-seed#quick-start) to install. + +#### Existing projects + +If you wish to migrate an existing project to PatternFly you must install and configure PatternFly React using either of these methods: + +* Using npm, run the following command: + ```sh + npm install @patternfly/react-core --save + ``` + +* Using Yarn, run the following command: + ```sh + yarn add @patternfly/react-core + ``` + +## Develop with HTML/CSS + +The PatternFly HTML/CSS library contains a collection of code samples that you can use to build interfaces with consistent PatternFly markup and styling. + +Each of the 3 modules (layouts, components, and utilities) delivers Sass (.scss) and CSS files that you can include in your build environment or consume from your page header. If you need to overwrite any elements, we recommend extending the variables found in the Sass files, rather than manually overwriting the CSS. + +When you install PatternFly, the package includes: + + * A single file for the entire compiled library: ```node_modules/@patternfly/patternfly/patternfly.css``` + * Individual files with each component compiled separately: ```node_modules/@patternfly/patternfly//styles.css``` + * A single file for the entire library's source: ```node_modules/@patternfly/patternfly/patternfly.scss``` + * Individual files for each component's source: ```node_modules/@patternfly/patternfly//styles.scss``` + +Use these files to consume the library. The recommended consumption approach will vary from project to project. + +### Install and configure PatternFly HTML/CSS + +1. Using npm, run the following command to install the HTML/CSS library: + + ```sh + npm install @patternfly/patternfly --save + ``` + +1. Navigate to the package you just installed to find the PatternFly CSS stylesheet, ```patternfly.css```, and copy it into your project's CSS directory. + +1. In your HTML file, link to your new PatternFly stylesheet by adding the following line to the bottom of your list of CSS files: + + ```html noLive + + ``` +
+ This will ensure that PatternFly styles take precedence over anything that currently resides in your application. + +1. If you want to use PatternFly utilities in your project, find the utilities file, ```patternfly-addons.css```, and copy it into your project’s CSS directory. + +1. In your HTML file, add the following line to the bottom of your list of CSS files: + + ```html noLive + + ``` + +### Using icons + +PatternFly uses [Font Awesome 5](https://fontawesome.com/), which can be utilized in 2 different ways: + + * **Built into PatternFly:** By default, Font Awesome is included as part of the PatternFly CSS file. You do not need to do anything else to use this icon font family. + + * **Used as a CDN:** If you wish to use the CDN for Font Awesome 5 rather than the default approach, you need to complete the following steps: + 1. Update the ```sass-utilities/scss-variables.scss``` file (from source ```node_modules/@patternfly/patternfly/```) to include: + + ```scss + $pf-v6-global--enable-fontawesome-cdn: true !default; + ``` + + 1. Build PatternFly as part of your build process. + +## Testing + +Many PatternFly components comply with the Open UI Automation (OUIA) guidelines, which are designed to ease the burden of creating and maintaining automated testing environments. Additional details about OUIA and the full list of compliant components [can be found in our developer resources.](/developer-resources/open-ui-automation) + +## Supported browsers and operating systems + +PatternFly is supported on the 2 latest major versions of the following browsers: +- Chrome +- Firefox +- Safari +- Edge + +## Breaking changes + +A breaking change is any modification to our design system that is significant enough to require intervention to ensure proper functionality in a UI built with PatternFly. These changes can occur in both the code and design of PatternFly features. To minimize major and unexpected disruptions, PatternFly typically reserves breaking changes for major version releases, with the following exceptions: +- Critical bug fixes reported outside of the major release schedule. +- Updates to components and features labeled as "beta." + +### Design breaking changes + +Breaking changes in PatternFly’s design include visual changes that would alter the UI and significantly disrupt the user experience. To restore the proper visual functioning of a UI, intentional updates are required to account for the changes. + +These changes include: +- Significant changes to a component’s style, which may be different enough to confuse users. +- Increases in the size of text or spacers that forcibly change content layout in a UI in ways that aren’t desired. + +### Core CSS breaking changes + +Breaking changes to our core CSS library are the result of code changes that include: +- CSS variables: + - Removing or renaming a CSS variable. + - Repurposing or changing the role of a CSS variable. + - Changing the relationship between tokens in the semantic layer (tokens that start with `--pf-t` and do not end in a number). +- Class names: + - Removing or renaming a class. + - Making a class required that was not previously required. + +### React breaking changes + +Breaking changes to our React library are the result of code changes that include: +- Component props: + - Removing a prop. + - Changing the name, type, role, or function of a prop. + - Making a prop required that was not previously required. +- Dependencies: + - Changes that alter component behavior. + - Changes that alter a consumer’s build process. + - Changes to the signature of an event handler. + diff --git a/packages/site/src/content/get-started/get-started.css b/packages/site/src/content/get-started/get-started.css new file mode 100644 index 0000000000..2ad08a2fc7 --- /dev/null +++ b/packages/site/src/content/get-started/get-started.css @@ -0,0 +1,12 @@ +.ws-content-blueArrow { + color: #0066CC; +} + +.ws-images { + margin: auto; + width: 600px; +} + +#supported-browsers.ws-title + table { + margin-bottom: 16px; +} diff --git a/packages/site/src/content/get-started/img/codemod-output.png b/packages/site/src/content/get-started/img/codemod-output.png new file mode 100644 index 0000000000..a243404b7a Binary files /dev/null and b/packages/site/src/content/get-started/img/codemod-output.png differ diff --git a/packages/site/src/content/get-started/img/deprecated-component.png b/packages/site/src/content/get-started/img/deprecated-component.png new file mode 100644 index 0000000000..07ad9551e0 Binary files /dev/null and b/packages/site/src/content/get-started/img/deprecated-component.png differ diff --git a/packages/site/src/content/get-started/img/layer-styles.png b/packages/site/src/content/get-started/img/layer-styles.png new file mode 100644 index 0000000000..1983f2355f Binary files /dev/null and b/packages/site/src/content/get-started/img/layer-styles.png differ diff --git a/packages/site/src/content/get-started/img/library-update.png b/packages/site/src/content/get-started/img/library-update.png new file mode 100644 index 0000000000..38ad0479e1 Binary files /dev/null and b/packages/site/src/content/get-started/img/library-update.png differ diff --git a/packages/site/src/content/get-started/img/menu-toggle-status.png b/packages/site/src/content/get-started/img/menu-toggle-status.png new file mode 100644 index 0000000000..41030e3cfa Binary files /dev/null and b/packages/site/src/content/get-started/img/menu-toggle-status.png differ diff --git a/packages/site/src/content/get-started/img/pf-figma-header.png b/packages/site/src/content/get-started/img/pf-figma-header.png new file mode 100644 index 0000000000..1cb04bb08b Binary files /dev/null and b/packages/site/src/content/get-started/img/pf-figma-header.png differ diff --git a/packages/site/src/content/get-started/img/pf4-selectable-card.png b/packages/site/src/content/get-started/img/pf4-selectable-card.png new file mode 100644 index 0000000000..a9b1377936 Binary files /dev/null and b/packages/site/src/content/get-started/img/pf4-selectable-card.png differ diff --git a/packages/site/src/content/get-started/img/pf5-selectable-card.png b/packages/site/src/content/get-started/img/pf5-selectable-card.png new file mode 100644 index 0000000000..a078cb5874 Binary files /dev/null and b/packages/site/src/content/get-started/img/pf5-selectable-card.png differ diff --git a/packages/site/src/content/get-started/img/quickstarts-bookmark.png b/packages/site/src/content/get-started/img/quickstarts-bookmark.png new file mode 100644 index 0000000000..e46944a312 Binary files /dev/null and b/packages/site/src/content/get-started/img/quickstarts-bookmark.png differ diff --git a/packages/site/src/content/get-started/img/sketch-cloud.png b/packages/site/src/content/get-started/img/sketch-cloud.png new file mode 100644 index 0000000000..31d326d550 Binary files /dev/null and b/packages/site/src/content/get-started/img/sketch-cloud.png differ diff --git a/packages/site/src/content/get-started/img/symbol-library.png b/packages/site/src/content/get-started/img/symbol-library.png new file mode 100644 index 0000000000..58997d4966 Binary files /dev/null and b/packages/site/src/content/get-started/img/symbol-library.png differ diff --git a/packages/site/src/content/get-started/img/template-padding.png b/packages/site/src/content/get-started/img/template-padding.png new file mode 100644 index 0000000000..842dedc8ff Binary files /dev/null and b/packages/site/src/content/get-started/img/template-padding.png differ diff --git a/packages/site/src/content/get-started/img/text-styles.png b/packages/site/src/content/get-started/img/text-styles.png new file mode 100644 index 0000000000..3cc568e024 Binary files /dev/null and b/packages/site/src/content/get-started/img/text-styles.png differ diff --git a/packages/site/src/content/get-started/img/topology-pipeline-arrows.png b/packages/site/src/content/get-started/img/topology-pipeline-arrows.png new file mode 100644 index 0000000000..b2642d97f7 Binary files /dev/null and b/packages/site/src/content/get-started/img/topology-pipeline-arrows.png differ diff --git a/packages/site/src/content/get-started/img/topology-pipeline-expansion.png b/packages/site/src/content/get-started/img/topology-pipeline-expansion.png new file mode 100644 index 0000000000..11bd53f9a0 Binary files /dev/null and b/packages/site/src/content/get-started/img/topology-pipeline-expansion.png differ diff --git a/packages/site/src/content/get-started/img/topology-pipeline-groups.png b/packages/site/src/content/get-started/img/topology-pipeline-groups.png new file mode 100644 index 0000000000..5b7050083d Binary files /dev/null and b/packages/site/src/content/get-started/img/topology-pipeline-groups.png differ diff --git a/packages/site/src/content/get-started/img/topology-vertical-pipelines.png b/packages/site/src/content/get-started/img/topology-vertical-pipelines.png new file mode 100644 index 0000000000..7387a8406c Binary files /dev/null and b/packages/site/src/content/get-started/img/topology-vertical-pipelines.png differ diff --git a/packages/site/src/content/get-started/release-highlights.mdx b/packages/site/src/content/get-started/release-highlights.mdx new file mode 100644 index 0000000000..cef730fe87 --- /dev/null +++ b/packages/site/src/content/get-started/release-highlights.mdx @@ -0,0 +1,442 @@ +--- +id: Release highlights +title: Release highlights +section: get-started +--- +import './get-started.css'; +import { Divider, Timestamp } from '@patternfly/react-core'; + +April 2025 + +## PatternFly 6.2 + +For the Q2 2025 PatternFly release we made progress in a few of our key initiatives, including PatternFly 6 migration enablement, component animations, React 19 support, and the continued evolution of PatternFly AI. Updates for these key areas can be found here, in this quarter's release highlights. + +### Promoted package versions + +The following packages were promoted with this release. Outside of our primary initiatives for this release, we addressed reported bugs and continued to enhance PatternFly with new features, as detailed in the linked changelogs. + +- patternfly/patternfly ([changelog](https://github.com/patternfly/patternfly/releases/tag/v6.2.0)) + - [@patternfly/patternfly@6.2.0](https://www.npmjs.com/package/@patternfly/patternfly) +- patternfly/react ([changelog](https://github.com/patternfly/patternfly-react/releases/tag/v6.2.0)) + - [@patternfly/react-charts@8.2.0](https://www.npmjs.com/package/@patternfly/react-charts) + - [@patternfly/react-code-editor@6.2.0](https://www.npmjs.com/package/@patternfly/react-code-editor) + - [@patternfly/react-core@6.2.0](https://www.npmjs.com/package/@patternfly/react-core) + - [@patternfly/react-drag-drop@6.2.0](https://www.npmjs.com/package/@patternfly/react-drag-drop) + - [@patternfly/icons@1.0.4](https://www.npmjs.com/package/@patternfly/icons) + - [@patternfly/react-styles@6.2.0](https://www.npmjs.com/package/@patternfly/react-styles) + - [@patternfly/react-table@6.2.0](https://www.npmjs.com/package/@patternfly/react-table) + - [patternfly/react-templates@6.2.0](https://www.npmjs.com/package/@patternfly/react-templates) + - [@patternfly/react-tokens@6.2.0](https://www.npmjs.com/package/@patternfly/react-tokens) +- PatternFly extensions + - [@patternfly/chatbot@2.2.0](https://www.npmjs.com/package/@patternfly/chatbot) ([changelog](https://github.com/patternfly/chatbot/releases/tag/v2.2.0)) + - [@patternfly/quickstarts@6.2.0](https://www.npmjs.com/package/@patternfly/quickstarts) ([changelog](https://github.com/patternfly/patternfly-quickstarts/releases/tag/v6.2.0)) + - [@patternfly/react-catalog-view-extension@6.1.0](https://www.npmjs.com/package/@patternfly/react-catalog-view-extension) ([changelog](https://github.com/patternfly/react-catalog-view/releases/tag/v6.1.0)) + - [@patternfly/react-component-groups@6.2.0](https://www.npmjs.com/package/@patternfly/react-component-groups) ([changelog](https://github.com/patternfly/react-component-groups/releases/tag/v6.2.0)) + - [@patternfly/react-log-viewer@6.1.0](https://www.npmjs.com/package/@patternfly/react-log-viewer) ([changelog](https://github.com/patternfly/react-log-viewer/releases/tag/v6.1.0)) +- [@patternfly/react-topology@6.2.0](https://www.npmjs.com/package/@patternfly/react-topology) ([changelog](https://github.com/patternfly/react-topology/releases/tag/v6.2.0)) + - [@patternfly/react-user-feedback@6.1.0](https://www.npmjs.com/package/@patternfly/react-user-feedback) ([changelog](https://github.com/patternfly/react-user-feedback/releases/tag/v6.1.0)) + +### PatternFly 6 enablement + +As products have continued their PatternFly 6 migration journeys, we've received helpful feedback on the upgrade process, including common roadblocks and situations that could use more guidance. So, we expanded and reorganized the [PatternFly 6 upgrade guide](/get-started/upgrade) to more clearly and comprehensively support the upgrade process. + +### Component animations + +Our highly-anticipated animations project focuses on integrating motion design into PatternFly components, to enhance user experiences and provide additional cues for interaction. You can keep track of this project via [our micro-animations roadmap](https://github.com/orgs/patternfly/projects/16/views/23?pane=issue&itemId=86507128&issue=patternfly%7Cpf-roadmap%7C215). + +Note that animations will either be specified as opt-in or opt-out: +- **Opt-in:** Requires additional updates to your codebase in order to function properly. These could cause test failures, depending on how your testing is set up, so you must manually opt into these animations and configure them appropriately. +- **Opt-out:** Turned on by default. To disable these animations, work with the PatternFly team to find a solution. + +With this release, 3 components now support animations: + +1. [Alert](/components/alert) + - **Animation type:** Opt-in. + - **Animation behavior:** For alerts within a group, there's a slide-in animation as new alerts are received and a slide-out animation as alerts are dismissed. + - **Example:** To visualize the motion behavior, you can interact with our website examples, which have opted in to animations. + - **Note:** By default, alert animations are opt-in and will only apply to alerts within an alert group. Opting into animations could require test updates. To ensure your test pass, the quickest solution is to set `hasAnimations` to `false`. Additionally, when alerts are dynamically added to a group, you must ensure that new alerts are prepended to the alert group list, rather than appended to the end of it. +1. [Navigation](/components/navigation) + - **Animation type:** Opt-out. + - **Animation behavior:** For expandable navigation items, the sub-menu fades in and out as navigation items are expanded and collapsed. + - **Example:** As an opt-out animation, you can see this motion behavior by default across expandable navigation items. +1. [Notification badge](/components/notification-badge) + - **Animation type:** Opt-in. + - **Animation behavior:** When the animation is triggered (for example, when a new notification arrives), the bell icon has a "ring" animation. + - **Example:** To illustrate the motion behavior of this animation, we added a [notification badge "With animations" example](/components/notification-badge#with-animation). + +### React 19 support + +We’ve made significant progress towards React 19 support in PatternFly, which is being tracked in [the React 19 roadmap](https://github.com/patternfly/pf-roadmap/issues/201). Our remaining work involves updating our React dependencies, testing version support, and creating any necessary support resources or documentation. + +### PatternFly AI + +In the world of PatternFly AI, we've continued our focus on expanding our ChatBot extension. As more Flyers have used ChatBot, we've gained insight into the types of new features that would have the most impact. To make progress on growing ChatBot needs, this release adds *many* new features, including [an inline drawer display mode](https://patternfly-org-pr-4493-site.surge.sh/patternfly-ai/chatbot/overview/demo/#inline-drawer-chatbot), the ability for users to give [message feedback](https://patternfly-org-pr-4493-site.surge.sh/patternfly-ai/chatbot/messages#message-feedback), [support for quick starts](https://patternfly-org-pr-4493-site.surge.sh/patternfly-ai/chatbot/messages#messages-with-quick-start-tiles), additional content types for [messages](/patternfly-ai/chatbot/messages#bot-messages), and much more. + +To see a complete list of new ChatBot features, [view the changelog](https://github.com/patternfly/chatbot/releases/tag/v2.2.0). + +Along with these new features, we've updated our documentation: +- [The ChatBot design guidelines](/patternfly-ai/chatbot/overview/design-guidelines) have been updated to reflect new features, expand on previous guidance, and add higher-level patterns for ChatBots usage in products. +- New [ChatBot analytics documentation](/patternfly-ai/chatbot/analytics) is also now available, which provides general guidance on the implementation of analytics tracking. + +### Expanded chart library +PatternFly has historically provided a charting solution using the [Victory](https://formidable.com/open-source/victory/docs/victory-chart/) chart library. With this release, PatternFly is also now delivering 2 charts based on the [Apache ECharts](https://echarts.apache.org/) library, including [a line chart](/charts/line-chart/EChart) and [a Sankey chart](/charts/sankey-chart). + +Additionally, EChart is now listed as a peer dependency for PatternFly. To use these new chart solutions, add 'echart' to your project dependencies and follow PatternFly's documentation to build out your charts. + +### Notable changes + +Outside of our key initiatives, there are a few notable changes that may require changes to your codebase and tests. + +#### Components +- Button + - **Change:** The `aria-disabled` will now only render when `true`, not on elements where it is `false` or `undefined`. + - **Required update:** Update tests that either: + - Check for `aria-disabled` to be `false` + - Match the disabled property +- Charts + - **Change:** Errors related to Victory 37.3.4 have been addressed. + - **Required update:** If you're using PatternFly 5, use [react-charts](https://www.npmjs.com/package/@patternfly/react-charts) v7.4.8 with Victory v37.3.4 or later. + +- Table + - **Change:** The [column management](/components/table/react-demos#column-management) and [column management with draggable](/components/table/react-demos#column-management-with-draggable) features have been rewritten to replace the use of the deprecated `` component. + - **Required update:** Remove the deprecated `` component by referring to the updated table demos. + +#### Extensions +- ChatBot + - **Change:** DOMpurify is no longer a dependency. + - **Required update:** Uninstall/remove DOMpurify from your codebases. +- ChatBot + - **Change:** `` is now a [PatternFly `