@bcgov/design-system-react-components 0.8.1-pr867 → 0.8.1-pr869

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 (3) hide show
  1. package/AGENTS.md +69 -0
  2. package/README.md +27 -0
  3. package/package.json +2 -1
package/AGENTS.md ADDED
@@ -0,0 +1,69 @@
1
+ # B.C. Design System React Components (v0.0.1)
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
+ - Prefer the component library API over creating new components wherever possible
12
+ - Use component props and established patterns rather than bypassing them with ad hoc markup
13
+ - When a component is missing or insufficient, extend existing design system patterns rather than creating one-off UI
14
+ - In this case, prefer using [React Aria primitives](https://react-aria.adobe.com) wherever possible
15
+
16
+ ### Component documentation
17
+
18
+ - Technical docs for components are in [Storybook](https://github.com/bcgov/design-system/tree/main/packages/react-components/src/stories)
19
+ - For components based on React Aria primitives, also refer to the React Aria docs for the full API reference
20
+
21
+ ### Available components
22
+
23
+ | Component | Summary | Component MDX file | React Aria primitive |
24
+ | --------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
25
+ | AlertBanner | Displays an important status or announcement message. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/AlertBanner.mdx | N/A |
26
+ | AlertDialog | Presents a high-priority confirmation or warning dialog. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/AlertDialog.mdx | https://react-aria.adobe.com/Dialog.md |
27
+ | Accordion | Expands and collapses sections of content. | N/A | https://react-aria.adobe.com/Disclosure.md |
28
+ | AccordionGroup | Groups related expandable sections together. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/AccordionGroup.mdx | https://react-aria.adobe.com/DisclosureGroup.md |
29
+ | Button | Triggers an action or navigates to a new state. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/Button.mdx | https://react-aria.adobe.com/Button.md |
30
+ | ButtonGroup | Groups related action buttons. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/ButtonGroup.mdx | N/A |
31
+ | Calendar | Lets users browse and select dates. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/Calendar.mdx | https://react-aria.adobe.com/Calendar.md |
32
+ | Callout | Highlights informational content or tips. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/Callout.mdx | N/A |
33
+ | Checkbox | Enables a true/false selection. | N/A | https://react-aria.adobe.com/Checkbox.md |
34
+ | CheckboxGroup | Lets users choose multiple related options. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/CheckboxGroup.mdx | https://react-aria.adobe.com/CheckboxGroup.md |
35
+ | DatePicker | Lets users select a date in a calendar-based input. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/DatePicker.mdx | https://react-aria.adobe.com/DatePicker.md |
36
+ | Dialog | Displays a modal dialog for focused workflow or messaging. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/Dialogs.mdx | https://react-aria.adobe.com/Dialog.md |
37
+ | Footer | Shows common site or page footer information. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/Footer.mdx | N/A |
38
+ | Form | Organizes fields and a submit flow. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/Form.mdx | https://react-aria.adobe.com/Form.md |
39
+ | Header | Displays a page or section header. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/Header.mdx | N/A |
40
+ | InlineAlert | Communicates a short, inline status message. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/InlineAlert.mdx | N/A |
41
+ | Menu, MenuItem, MenuTrigger, SubmenuTrigger, MenuSection, MenuSectionHeader | Displays a menu of actions or navigation choices. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/Menu.mdx | https://react-aria.adobe.com/Menu.md |
42
+ | Modal | Displays a layered overlay for focused interaction. | N/A | https://react-aria.adobe.com/Modal.md |
43
+ | NumberField | Lets users input numeric values with validation. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/NumberField.mdx | https://react-aria.adobe.com/NumberField.md |
44
+ | ProgressBar | Shows completion progress for a long-running task. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/ProgressBar.mdx | https://react-aria.adobe.com/ProgressBar.md |
45
+ | ProgressCircle | Shows a circular progress indicator. | N/A | https://react-aria.adobe.com/ProgressBar.md |
46
+ | RadioGroup, Radio | Lets users choose one option from a set. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/RadioGroup.mdx | https://react-aria.adobe.com/RadioGroup.md |
47
+ | Select | Lets users choose one option from a dropdown list. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/Select.mdx | https://react-aria.adobe.com/Select.md |
48
+ | Separator | Visually separates content sections. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/Separator.mdx | https://react-aria.adobe.com/Separator.md |
49
+ | Subheader | Provides a secondary heading or section label. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/Subheader.mdx | N/A |
50
+ | Switch | Toggles a setting between on and off. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/Switch.mdx | https://react-aria.adobe.com/Switch.md |
51
+ | TagGroup, TagList, Tag | Displays small labels or filtered selections. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/TagGroup.mdx | https://react-aria.adobe.com/TagGroup.md |
52
+ | TextArea, TextField | Accepts short or multi-line text input. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/TextField.mdx | https://react-aria.adobe.com/TextField.md |
53
+ | TimeField | Lets users input a time value. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/TimeField.mdx | https://react-aria.adobe.com/TimeField.md |
54
+ | ToggleButton | Toggles an action between active and inactive states. | N/A | https://react-aria.adobe.com/ToggleButton.md |
55
+ | ToggleButtonGroup | Groups related toggle actions together. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/ToggleButtonGroup.mdx | https://react-aria.adobe.com/ToggleButtonGroup.md |
56
+ | Tooltip, TooltipTrigger | Shows contextual help or extra information on hover or focus. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/Tooltip.mdx | https://react-aria.adobe.com/Tooltip.md |
57
+ | Heading | Renders a styled semantic heading. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/Heading.mdx | https://react-spectrum.adobe.com/v3/Heading.html |
58
+ | Link | Renders an accessible, configurable hyperlink. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/Link.mdx | https://react-spectrum.adobe.com/v3/Link.html |
59
+ | Text | Renders styled text content. | https://github.com/bcgov/design-system/blob/main/packages/react-components/src/stories/Text.mdx | https://react-spectrum.adobe.com/v3/Text.html |
60
+
61
+ ## Styling components
62
+
63
+ - Component CSS is bundled internally
64
+ - Do not overwrite the `className` for design system components
65
+ - Components are designed to work well in flexbox and grid layouts
66
+ - The design system does not assume or enforce a specific grid or layout convention
67
+ - If writing new components, use design tokens from the `@bcgov/design-tokens` library to ensure coherence with other components
68
+ - Prefer component-level styling and design tokens over bespoke CSS
69
+ - Refer to additional instructions for working with design tokens in `node_modules/@bcgov/design-tokens/AGENTS.md`
package/README.md CHANGED
@@ -129,6 +129,33 @@ This project follows semantic versioning. See [CHANGELOG.md](./CHANGELOG.md) for
129
129
 
130
130
  ## Development
131
131
 
132
+ ### Development Principles
133
+
134
+ - 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.
135
+ - 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).
136
+ - 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).
137
+ - We endeavour to release a major version 1 as soon as we consider our initial component set complete.
138
+ - 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.
139
+ - 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`.
140
+ - 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:
141
+ - 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.
142
+ - 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)).
143
+ - 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).
144
+ - 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.
145
+ - We don't use a CSS framework like Tailwind or Bootstrap.
146
+ - 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.
147
+ - Nitty gritty code details below:
148
+ - Class names:
149
+ - Class names start like this:
150
+ - When a React Aria component is being styled: `.bcds-react-aria-<RACComponentName>`
151
+ - 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.
152
+ - When a generic HTML tag is the top level component: `.bcds-<ComponentName>`
153
+ - For example, the `Header` and `Footer` are just `<header>` and `<footer>` elements, not components from RAC.
154
+ - Class names use vaguely BEM-like conventions after the first chunk. Ex: `.bcds-react-aria-Disclosure--Panel`
155
+ - 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.
156
+ - 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.
157
+ - 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/).
158
+
132
159
  ### Components
133
160
 
134
161
  Components live in `./src/components` and are targeted by the build process with an export in `./src/index.ts`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bcgov/design-system-react-components",
3
- "version": "0.8.1-pr867",
3
+ "version": "0.8.1-pr869",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "git+https://github.com/bcgov/design-system.git",
@@ -39,6 +39,7 @@
39
39
  }
40
40
  },
41
41
  "files": [
42
+ "AGENTS.md",
42
43
  "dist/index.d.ts",
43
44
  "dist/esm",
44
45
  "dist/cjs"