@bcgov/design-system-react-components 0.8.1 → 0.9.0-pr911

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/AGENTS.md +83 -0
  2. package/README.md +44 -1
  3. package/dist/cjs/index.cjs +3688 -3450
  4. package/dist/cjs/index.cjs.map +1 -1
  5. package/dist/esm/index.js +3687 -3449
  6. package/dist/esm/index.js.map +1 -1
  7. package/dist/index.d.ts +144 -76
  8. package/package.json +37 -31
package/AGENTS.md ADDED
@@ -0,0 +1,83 @@
1
+ # B.C. Design System React Components
2
+
3
+ ## Library context
4
+
5
+ - This React component library is part of the [B.C. Design System](https://gov.bc.ca/designsystem)
6
+ - Use this library when composing UI in a React project for the B.C. government
7
+
8
+ ## Using the component library
9
+
10
+ - Install the React components package with `npm i @bcgov/design-system-react-components` and import individual components as needed
11
+ - Check that `@bcgov/bc-sans` is installed and `@bcgov/bc-sans/css/BC_Sans.css` is imported. Warn the user and refer them to the `@bcgov/bc-sans` README if not
12
+ - Prefer the component library API over creating new components wherever possible
13
+ - Use component props and established patterns rather than bypassing them with ad hoc markup
14
+ - When a component is missing or insufficient, extend existing design system patterns rather than creating one-off UI
15
+ - In this case, prefer using [React Aria primitives](https://react-aria.adobe.com) wherever possible
16
+
17
+ ### Component documentation
18
+
19
+ - Technical docs for components are in [Storybook](https://github.com/bcgov/design-system/tree/main/packages/react-components/src/stories)
20
+ - For components based on React Aria primitives, also refer to the React Aria docs for the full API reference
21
+ - All component props are fully typed. Treat the shipped TypeScript types — via your editor's autocomplete, or read directly from `dist/index.d.ts` inside `node_modules/@bcgov/design-system-react-components` — as the authoritative prop reference
22
+ - If a prop isn't present in the types, it doesn't exist. Don't infer props from naming conventions or from other component libraries
23
+
24
+ ### Available components
25
+
26
+ | Component | Summary | Component MDX file | React Aria primitive |
27
+ | --------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
28
+ | AlertBanner | Displays an important status or announcement message. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/AlertBanner.mdx | N/A |
29
+ | AlertDialog | Presents a high-priority confirmation or warning dialog. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/AlertDialog.mdx | https://react-aria.adobe.com/Dialog.md |
30
+ | Accordion | Expands and collapses sections of content. | N/A | https://react-aria.adobe.com/Disclosure.md |
31
+ | AccordionGroup | Groups related expandable sections together. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/AccordionGroup.mdx | https://react-aria.adobe.com/DisclosureGroup.md |
32
+ | Button | Triggers an action or navigates to a new state. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/Button.mdx | https://react-aria.adobe.com/Button.md |
33
+ | ButtonGroup | Groups related action buttons. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/ButtonGroup.mdx | N/A |
34
+ | Calendar | Lets users browse and select dates. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/Calendar.mdx | https://react-aria.adobe.com/Calendar.md |
35
+ | Callout | Highlights informational content or tips. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/Callout.mdx | N/A |
36
+ | Checkbox | Enables a true/false selection. | N/A | https://react-aria.adobe.com/Checkbox.md |
37
+ | CheckboxGroup | Lets users choose multiple related options. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/CheckboxGroup.mdx | https://react-aria.adobe.com/CheckboxGroup.md |
38
+ | DatePicker | Lets users select a date in a calendar-based input. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/DatePicker.mdx | https://react-aria.adobe.com/DatePicker.md |
39
+ | Dialog | Displays a modal dialog for focused workflow or messaging. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/Dialogs.mdx | https://react-aria.adobe.com/Dialog.md |
40
+ | Footer | Shows common site or page footer information. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/Footer.mdx | N/A |
41
+ | Form | Organizes fields and a submit flow. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/Form.mdx | https://react-aria.adobe.com/Form.md |
42
+ | Header | Displays a page or section header. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/Header.mdx | N/A |
43
+ | InlineAlert | Communicates a short, inline status message. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/InlineAlert.mdx | N/A |
44
+ | Menu, MenuItem, MenuTrigger, SubmenuTrigger, MenuSection, MenuSectionHeader | Displays a menu of actions or navigation choices. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/Menu.mdx | https://react-aria.adobe.com/Menu.md |
45
+ | Modal | Displays a layered overlay for focused interaction. | N/A | https://react-aria.adobe.com/Modal.md |
46
+ | NumberField | Lets users input numeric values with validation. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/NumberField.mdx | https://react-aria.adobe.com/NumberField.md |
47
+ | ProgressBar | Shows completion progress for a long-running task. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/ProgressBar.mdx | https://react-aria.adobe.com/ProgressBar.md |
48
+ | ProgressCircle | Shows a circular progress indicator. | N/A | https://react-aria.adobe.com/ProgressBar.md |
49
+ | RadioGroup, Radio | Lets users choose one option from a set. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/RadioGroup.mdx | https://react-aria.adobe.com/RadioGroup.md |
50
+ | Select | Lets users choose one option from a dropdown list. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/Select.mdx | https://react-aria.adobe.com/Select.md |
51
+ | Separator | Visually separates content sections. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/Separator.mdx | https://react-aria.adobe.com/Separator.md |
52
+ | Subheader | Provides a secondary heading or section label. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/Subheader.mdx | N/A |
53
+ | Switch | Toggles a setting between on and off. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/Switch.mdx | https://react-aria.adobe.com/Switch.md |
54
+ | TagGroup, TagList, Tag | Displays small labels or filtered selections. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/TagGroup.mdx | https://react-aria.adobe.com/TagGroup.md |
55
+ | TextArea, TextField | Accepts short or multi-line text input. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/TextField.mdx | https://react-aria.adobe.com/TextField.md |
56
+ | TimeField | Lets users input a time value. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/TimeField.mdx | https://react-aria.adobe.com/TimeField.md |
57
+ | ToggleButton | Toggles an action between active and inactive states. | N/A | https://react-aria.adobe.com/ToggleButton.md |
58
+ | ToggleButtonGroup | Groups related toggle actions together. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/ToggleButtonGroup.mdx | https://react-aria.adobe.com/ToggleButtonGroup.md |
59
+ | Tooltip, TooltipTrigger | Shows contextual help or extra information on hover or focus. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/Tooltip.mdx | https://react-aria.adobe.com/Tooltip.md |
60
+ | Heading | Renders a styled semantic heading. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/Heading.mdx | https://react-spectrum.adobe.com/v3/Heading.html |
61
+ | Link | Renders an accessible, configurable hyperlink. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/Link.mdx | https://react-spectrum.adobe.com/v3/Link.html |
62
+ | Text | Renders styled text content. | https://raw.githubusercontent.com/bcgov/design-system/main/packages/react-components/src/stories/Text.mdx | https://react-spectrum.adobe.com/v3/Text.html |
63
+
64
+ ### Forms
65
+
66
+ - Use the Form component as a wrapper for input components
67
+ - Refer to the [React Aria forms docs](https://react-aria.adobe.com/forms.md) when implementing validation and submission in your application
68
+ - Use components' built-in state, validation and error handling APIs instead of writing your own
69
+
70
+ ### Icons
71
+
72
+ - The library includes React components for a small number of common icons
73
+ - If you need additional icons, prefer using Font Awesome Free v7 (`@fortawesome/react-fontawesome@3.5.0` or later) for coherence with the design system
74
+
75
+ ## Styling components
76
+
77
+ - Component CSS is bundled internally
78
+ - Do not overwrite the `className` for design system components
79
+ - Components are designed to work well in flexbox and grid layouts
80
+ - The design system does not assume or enforce a specific grid or layout convention
81
+ - If writing new components, use design tokens from the `@bcgov/design-tokens` library to ensure coherence with other components
82
+ - Prefer component-level styling and design tokens over bespoke CSS
83
+ - Refer to additional instructions for working with design tokens in `node_modules/@bcgov/design-tokens/AGENTS.md`
package/README.md CHANGED
@@ -17,6 +17,16 @@ If you have questions, you can:
17
17
 
18
18
  `npm install @bcgov/design-system-react-components`
19
19
 
20
+ ### Using this library with LLMs
21
+
22
+ Instructions for AI agents are shipped with this library (`/node_modules/@bcgov/design-system-react-components/AGENTS.md`).
23
+
24
+ Add the B.C. Design System boilerplate from [AGENTS.example.md](https://github.com/bcgov/design-system/blob/main/AGENTS.example.md) to an `AGENTS.md` file at the root of your project. This directs agents to load the library-specific instructions.
25
+
26
+ Run `/context` to confirm that your agent has loaded the instructions into its context window.
27
+
28
+ When working with Figma design files that use the B.C. Design System, [connecting your harness to Figma's MCP server](https://developers.figma.com/docs/figma-mcp-server/) can also significantly improve output quality.
29
+
20
30
  ### BC Sans font dependency
21
31
 
22
32
  This package installs [@bcgov/bc-sans](https://www.npmjs.com/package/@bcgov/bc-sans) as a peer dependency. You must import the font-face declarations from @bcgov/bc-sans and ensure the font is reachable for your end user. The React components require that the `BC Sans` font-face is available to display correctly. The components do not ship their own copies of the font to minimize your bundle size.
@@ -113,6 +123,8 @@ Most components are based on <a href="https://react-aria.adobe.com">React Aria</
113
123
 
114
124
  This package has a peer dependency on `react` and `react-dom` at these versions: `"^16.14.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0"`
115
125
 
126
+ If using React v16 or v17, you'll need to use an [SSRProvider](https://react-aria.adobe.com/SSRProvider) to prevent errors from components that rely on the [useId hook](https://react-aria.adobe.com/useId).
127
+
116
128
  By targeting v16.14.0 as a minimum, we get to use [React's modern JSX transformation](https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) in `tsconfig.json`:
117
129
 
118
130
  ```json
@@ -127,6 +139,33 @@ This project follows semantic versioning. See [CHANGELOG.md](./CHANGELOG.md) for
127
139
 
128
140
  ## Development
129
141
 
142
+ ### Development Principles
143
+
144
+ - We must maintain an **extremely high bar for accessibility**. For example, every action possible with a mouse needs to be possible with a keyboard (or other assistive technology). Adobe's `react-aria-components` is very adept at cross-device support for this, which is one of the main reasons we chose it as our base, un-styled component library.
145
+ - We endeavour to **follow semantic versioning**, though we have not yet released a major version 1. On v0, we are still willing to carefully make breaking changes if the alternative is painting ourselves into a corner. Our rationale here comes from [item #4 of the SemVer spec](https://semver.org/#spec-item-4).
146
+ - Once we are on a major version 1, we will be much more strict about only making breaking changes with major version bumps. [Here's an example of a breaking component change that we consider okay in v0](https://github.com/bcgov/design-system/pull/844#issuecomment-5431222716).
147
+ - We endeavour to release a major version 1 as soon as we consider our initial component set complete.
148
+ - We **do NOT want to make life hard for early adopters**, so we think very hard about breaking changes and we publish specific guidance with releases that involve breaks.
149
+ - We **keep our dependencies extremely minimal**. New `devDependencies` are fine and anticipated, but `dependencies` that get shipped with the library need very careful consideration. So far, we have only added dependencies from under the umbrella of Adobe's Spectrum design system, and only where it's necessary because a particular piece of functionality isn't exposed directly from `react-aria-components`.
150
+ - We want to **support as many new and existing React projects as possible**. To this end, we avoid dependencies that might conflict with existing choices in a project:
151
+ - We avoid importing BC Sans in case a project is already shipping it themselves. It's much worse to ship the heavy BC Sans font files twice in production than to show a generic serifed font in development until the developer figures out that something is wrong.
152
+ - The library should work on as wide a range of React versions as possible given the `react-aria-components` dependency. We chose to very slightly narrow their support version range to start our own support at v16.14.0. This is the version where it's no longer necessary to import unused `react` dependencies into every component file (see [Introducing the New JSX Transform](https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html)).
153
+ - Choices that make things harder for apps on older versions of React to adopt the library should be thought through. [Here's an example of thinking through a mitigation that affects React v16 and v17 projects](https://github.com/bcgov/design-system/pull/760#issuecomment-5321364758).
154
+ - We write our CSS styles without the use of a CSS-in-JS tool to avoid conflicts with any existing tools that existing projects might be using.
155
+ - We don't use a CSS framework like Tailwind or Bootstrap.
156
+ - We want to **keep all tests passing**. GitHub Actions is used to run test suites when a PR is made. PRs should not be merged to `main` if new breaks are introduced.
157
+ - Nitty gritty code details below:
158
+ - Class names:
159
+ - Class names start like this:
160
+ - When a React Aria component is being styled: `.bcds-react-aria-<RACComponentName>`
161
+ - React Aria Components are unstyled components that use default class names like `.react-aria-<RACComponentName>`. We append `bcds-` for "B.C. Design System" to scope our styles in case people are using RAC for other things.
162
+ - When a generic HTML tag is the top level component: `.bcds-<ComponentName>`
163
+ - For example, the `Header` and `Footer` are just `<header>` and `<footer>` elements, not components from RAC.
164
+ - Class names use vaguely BEM-like conventions after the first chunk. Ex: `.bcds-react-aria-Disclosure--Panel`
165
+ - We are not currently doing any kind of unique ID-based class name generation/scoping, so it's important to be somewhat verbose in selecting class names. If you accidentally reuse a class like `.bcds-react-aria-Button` as part of some composite selector, its styles will collide with the styles from the `Button` component.
166
+ - We always want to use tokens from our tokens library where possible. Where a hard-coded value is being used because no token is available, it's a good idea to raise it to the team so designers can make the call on whether a new token should be added or if a particular hard-coded value is a genuine one-off.
167
+ - We lint our styles with `stylelint`, and should endeavour to pass the [`no-descending-specificity` rule](https://stylelint.io/user-guide/rules/no-descending-specificity/).
168
+
130
169
  ### Components
131
170
 
132
171
  Components live in `./src/components` and are targeted by the build process with an export in `./src/index.ts`.
@@ -193,7 +232,11 @@ Then in a local React project folder, use `npm link @bcgov/design-system-react-c
193
232
 
194
233
  ### Linting
195
234
 
196
- ESLint is used for linting. See configuration file `eslint.config.js` and `lint` script in `package.json`.
235
+ ESLint is used for linting TypeScript files. See configuration file `eslint.config.js` and `lint:ts` script in `package.json`.
236
+
237
+ Stylelint is used for linting CSS files. See configuration file `stylelint.config.mjs` and `lint:css` script in `package.json`.
238
+
239
+ The `lint` script in `package.json` runs both the TypeScript and CSS linting in series.
197
240
 
198
241
  ### Formatting
199
242