If your project uses custom Vanilla SCSS variables, you can inject them into @canonical/react-components during the build process using the additionalData option in your bundler configuration. This ensures your custom definitions are processed before the component styles.

// Vite configuration
export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `
          $color-brand: #bada55;
          $breakpoint-large: 1234px;
        `,
      },
    },
  },
});

// Webpack configuration
module.exports = {
  module: {
    rules: [
      {
        test: /\.scss$/,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'sass-loader',
            options: {
              additionalData: `
                $color-brand: #bada55;
                $breakpoint-large: 1234px;
              `,
            },
          },
        ],
      },
    ],
  },
};

To use a local version of @canonical/react-components in a project running Yarn 3, both projects must reside on the same machine.

1. In react-components, clean, install, build, and start the build watcher.
2. In your project, clean, install, and link to the local path.
3. Resolve dependency mismatches by aligning versions in react-components with your project.
4. Add resolutions to your project's package.json to ensure react, react-dom, formik, and @canonical/react-components all point to the local node_modules of the library.

# In react-components
yarn clean
yarn install
yarn build
yarn build-watch

# In your project
yarn clean
yarn install
yarn link path_to_react_components

In your project's package.json

"resolutions": { "@canonical/react-components": "portal:path_to_react_components", "formik": "portal:path_to_react_components/node_modules/formik", "react": "portal:path_to_react_components/node_modules/react", "react-dom": "portal:path_to_react_components/node_modules/react-dom" }

For projects using older versions of Yarn, use dotrun to manage the linking process. This prevents errors like 'multiple copies of React being loaded'.

Workflow:

1. In react-components, run dotrun link-package and dotrun build-watch.
2. In your project, use dotrun exec yarn link for both the library and react, then run yarn install.
3. Start your project using yarn (do not use ./run).
4. When finished, unlink the packages in your project and run dotrun unlink-package in react-components.

# In react-components
dotrun link-package
dotrun build-watch

# In your project
dotrun clean
dotrun exec yarn link "@canonical/react-components"
dotrun exec yarn link "react"
dotrun exec yarn install
dotrun

# Cleanup in your project
dotrun exec yarn unlink react
dotrun exec yarn unlink "@canonical/react-components"

# Cleanup in react-components
dotrun unlink-package

The Panel component uses an exclusive prop pattern for its header. You must choose one of the following approaches:

1. Default Header: Uses logo or title. If logo is provided, it takes precedence over title. You can also provide controls and toggle to augment this header.
2. Custom Header: Provide a header prop (a ReactNode) to completely replace the default header implementation.

Header Props Reference:

• logo: A ReactNode or a configuration object containing icon, iconAlt, name, nameAlt, and an optional component (defaults to a).
• title: A ReactNode for the panel title.
• titleComponent: The element used for the title (defaults to h4).
• titleClassName: CSS classes for the title element.
• titleId: An ID for the title element.
• controls: A ReactNode to be displayed in the controls area.
• controlsClassName: CSS classes for the controls element.
• stickyHeader: Boolean to make the header sticky.
• toggle: An object { label: string, onClick: () => void } to render a panel toggle button.
• header: A ReactNode that replaces the entire header area.

// Example of a Panel with a title, controls, and a toggle
<Panel 
  title="Settings"
  toggle={{ label: 'Collapse', onClick: () => console.log('toggled') }}
  controls={<button>Action</button>}
>
  <p>Settings content</p>
</Panel>