@cityofportland/components-react 1.0.0-alpha.2 → 1.0.0-alpha.4
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.
- package/README.md +30 -259
- package/dist/alert/alert.css +1 -0
- package/dist/alert/alert.d.ts +11 -0
- package/dist/alert/alert.es.js +3473 -0
- package/dist/alert/index.d.ts +1 -0
- package/dist/box/box.d.ts +51 -0
- package/dist/box/box.es.js +4 -0
- package/dist/box/index.d.ts +1 -0
- package/dist/button/button.css +1 -0
- package/dist/button/button.d.ts +9 -0
- package/dist/button/button.es.js +34 -0
- package/dist/button/index.d.ts +1 -0
- package/dist/city-seal/city-seal.css +1 -0
- package/dist/city-seal/city-seal.d.ts +18 -0
- package/dist/city-seal/city-seal.es.js +22 -0
- package/dist/city-seal/index.d.ts +1 -0
- package/dist/footer/footer.css +1 -0
- package/dist/footer/footer.d.ts +19 -0
- package/dist/footer/footer.es.js +10987 -0
- package/dist/footer/footer.test.d.ts +1 -0
- package/dist/footer/index.d.ts +1 -0
- package/dist/header/header.css +1 -0
- package/dist/header/header.d.ts +19 -0
- package/dist/header/header.es.js +43 -0
- package/dist/header/index.d.ts +1 -0
- package/dist/index/index.css +1 -0
- package/dist/index-C4cFhgXK.js +68 -0
- package/dist/index-IqW719eK.js +1484 -0
- package/dist/tag/index.d.ts +1 -0
- package/dist/tag/tag.css +1 -0
- package/dist/tag/tag.d.ts +7 -0
- package/dist/tag/tag.es.js +16 -0
- package/dist/utils.d.ts +3 -0
- package/package.json +8 -7
package/README.md
CHANGED
|
@@ -1,278 +1,49 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @cityofportland/components-react
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The React implementation of the design system. Vite builds each component as its
|
|
4
|
+
own ES module with matching TypeScript declarations and CSS, so you only ship
|
|
5
|
+
what you actually import.
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
Under the hood it's built on `@cityofportland/design-tokens` for values,
|
|
8
|
+
`@cityofportland/components-css` for styling, and `@cityofportland/types` for
|
|
9
|
+
shared prop contracts — so it stays in sync with the Lit and Drupal versions of
|
|
10
|
+
the same components.
|
|
6
11
|
|
|
7
|
-
##
|
|
8
|
-
|
|
9
|
-
Install the library in your project:
|
|
12
|
+
## Using it
|
|
10
13
|
|
|
11
14
|
```bash
|
|
12
|
-
pnpm add @cityofportland/
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
### Component-Level Imports (Recommended)
|
|
16
|
-
|
|
17
|
-
This approach provides optimal tree shaking by allowing you to import only the components and styles you need, resulting in the smallest possible bundle size.
|
|
18
|
-
|
|
19
|
-
1. **Import the component:**
|
|
20
|
-
|
|
21
|
-
```jsx
|
|
22
|
-
import { Button } from "@cityofportland/component-library/components/Button";
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
2. **Import the component's stylesheet:**
|
|
26
|
-
|
|
27
|
-
```jsx
|
|
28
|
-
import "@cityofportland/component-library/components/Button/style.css";
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
### Selective Theme Loading
|
|
32
|
-
|
|
33
|
-
You can import a specific theme to style your application. Choose one of the following:
|
|
34
|
-
|
|
35
|
-
```jsx
|
|
36
|
-
// PGOV Theme (Default)
|
|
37
|
-
import "@cityofportland/component-library/themes/pgov";
|
|
38
|
-
|
|
39
|
-
// PGOV Dark Theme
|
|
40
|
-
import "@cityofportland/component-library/themes/pgov-dark";
|
|
41
|
-
|
|
42
|
-
// USWDS Default Theme
|
|
43
|
-
import "@cityofportland/component-library/themes/uswds-default";
|
|
15
|
+
pnpm add @cityofportland/components-react
|
|
44
16
|
```
|
|
45
17
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
You can import the design tokens as a JavaScript object to use in your own custom components and styling.
|
|
18
|
+
React and React DOM are peer dependencies, so make sure your app already has
|
|
19
|
+
those installed. Import components one at a time to keep your bundle lean:
|
|
49
20
|
|
|
50
|
-
```
|
|
51
|
-
import {
|
|
21
|
+
```tsx
|
|
22
|
+
import { Button } from "@cityofportland/components-react/button";
|
|
23
|
+
import "@cityofportland/components-react/button.css";
|
|
52
24
|
|
|
53
|
-
|
|
54
|
-
<
|
|
55
|
-
|
|
56
|
-
backgroundColor: designTokens.color.primary.medium,
|
|
57
|
-
padding: designTokens.spacing.md,
|
|
58
|
-
}}
|
|
59
|
-
>
|
|
60
|
-
Hello, World!
|
|
61
|
-
</div>
|
|
62
|
-
);
|
|
25
|
+
export function Example() {
|
|
26
|
+
return <Button>Continue</Button>;
|
|
27
|
+
}
|
|
63
28
|
```
|
|
64
29
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
For applications that need to switch themes on the fly (e.g., a light/dark mode toggle), you can use the `themeLoader`.
|
|
68
|
-
|
|
69
|
-
```jsx
|
|
70
|
-
import { loadTheme } from "@cityofportland/component-library/themeLoader";
|
|
71
|
-
|
|
72
|
-
const ThemeToggleButton = ({ theme, setTheme }) => {
|
|
73
|
-
const toggleTheme = async () => {
|
|
74
|
-
const newTheme = theme === "pgov" ? "pgov-dark" : "pgov";
|
|
75
|
-
await loadTheme(newTheme);
|
|
76
|
-
setTheme(newTheme);
|
|
77
|
-
};
|
|
78
|
-
|
|
79
|
-
return <button onClick={toggleTheme}>Toggle Theme</button>;
|
|
80
|
-
};
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
## Contributing to the Library
|
|
84
|
-
|
|
85
|
-
### Quick Start
|
|
30
|
+
## Developing
|
|
86
31
|
|
|
87
32
|
```bash
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
# Install dependencies (using pnpm)
|
|
93
|
-
pnpm install
|
|
94
|
-
|
|
95
|
-
# Start Storybook
|
|
96
|
-
pnpm run storybook
|
|
33
|
+
turbo build --filter=@cityofportland/components-react
|
|
34
|
+
turbo dev --filter=@cityofportland/components-react
|
|
35
|
+
turbo storybook --filter=@cityofportland/components-react
|
|
36
|
+
turbo test --filter=@cityofportland/components-react
|
|
97
37
|
```
|
|
98
38
|
|
|
99
|
-
Storybook
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
- [Node.js](https://nodejs.org/) (v18 or higher)
|
|
104
|
-
- [pnpm](https://pnpm.io/) (v8 or higher)
|
|
105
|
-
|
|
106
|
-
To install pnpm:
|
|
107
|
-
|
|
108
|
-
```bash
|
|
109
|
-
npm install -g pnpm
|
|
110
|
-
```
|
|
111
|
-
|
|
112
|
-
## Available Scripts
|
|
113
|
-
|
|
114
|
-
- `pnpm run storybook` - Start Storybook development server
|
|
115
|
-
- `pnpm run build` - Build the component library
|
|
116
|
-
- `pnpm run build-storybook` - Build Storybook for production
|
|
117
|
-
- `pnpm test` - Run tests
|
|
118
|
-
- `pnpm run lint` - Run ESLint
|
|
119
|
-
- `pnpm run prepare` - Build the library (runs automatically on install)
|
|
120
|
-
|
|
121
|
-
## Project Structure
|
|
122
|
-
|
|
123
|
-
```
|
|
124
|
-
portland-component-library/
|
|
125
|
-
├── src/
|
|
126
|
-
│ ├── components/ # React components
|
|
127
|
-
│ │ ├── Accordion/ # Accordion content sections
|
|
128
|
-
│ │ ├── Alert/ # Alert messages and notifications
|
|
129
|
-
│ │ ├── Banner/ # Government website banner
|
|
130
|
-
│ │ ├── Breadcrumbs/# Navigation breadcrumbs
|
|
131
|
-
│ │ ├── Button/ # Button components
|
|
132
|
-
│ │ ├── ColorSwatch/# Color display and documentation
|
|
133
|
-
│ │ ├── Contacts/ # Contact information display
|
|
134
|
-
│ │ ├── Footer/ # Site footer with accessibility information
|
|
135
|
-
│ │ ├── Header/ # Generic USWDS Header wrapper with optional extended layout
|
|
136
|
-
│ │ ├── HeroGlobal/ # Global hero section with image and call-to-action
|
|
137
|
-
│ │ ├── HeroHomepage/# Homepage hero section
|
|
138
|
-
│ │ ├── Identifier/ # Agency identifier component
|
|
139
|
-
│ │ ├── LanguageSelector/ # Language selection dropdown component
|
|
140
|
-
│ │ ├── Modal/ # Modal dialog component
|
|
141
|
-
│ │ ├── PageTemplate/# Page template
|
|
142
|
-
│ │ ├── Pagination/ # USWDS-compliant pagination component
|
|
143
|
-
│ │ ├── Person/ # Profile block for individuals with avatar, name, role, and contact info
|
|
144
|
-
│ │ ├── PGOVHeader/ # Portland.gov navigation header
|
|
145
|
-
│ │ ├── ProcessSteps/# Process step indicators
|
|
146
|
-
│ │ ├── Search/ # Search input component
|
|
147
|
-
│ │ ├── SideNav/ # Side navigation
|
|
148
|
-
│ │ ├── SkipNav/ # Keyboard accessibility
|
|
149
|
-
│ │ ├── Spacing/ # Spacing utilities
|
|
150
|
-
│ │ ├── StepIndicator/# Horizontal step indicator
|
|
151
|
-
│ │ ├── SummaryBox/ # Summary information display
|
|
152
|
-
│ │ ├── Tag/ # Tag component for labeling and categorization
|
|
153
|
-
│ │ ├── Table/ # Table component for displaying tabular data
|
|
154
|
-
│ │ ├── Tooltip/ # Tooltip component
|
|
155
|
-
│ │ ├── Typography/ # Text components and styles
|
|
156
|
-
│ │ ├── Card/ # Card component for displaying content in a styled container
|
|
157
|
-
│ │ ├── CardFlag/ # Card component with media and content layout
|
|
158
|
-
│ │ ├── CardGrid/ # Grid layout for Card components
|
|
159
|
-
│ │ ├── Dropdown/ # Accessible custom dropdown/select component
|
|
160
|
-
│ │ ├── ExternalLinkIcon.jsx # External link icon component
|
|
161
|
-
│ │ ├── PopoverWithCard/# Popover for displaying interactive Card content
|
|
162
|
-
│ │ ├── RadioButtons/ # Accessible radio button component with multiple variants
|
|
163
|
-
│ │ ├── TextArea/ # Text area component for multi-line text input
|
|
164
|
-
│ │ ├── TextInput/ # Text input component with validation and states
|
|
165
|
-
│ │ └── Checkbox/ # Checkbox component allowing multiple selections from a list
|
|
166
|
-
│ ├── images/ # Image assets
|
|
167
|
-
│ └── styles/ # SCSS styles and themes
|
|
168
|
-
├── .storybook/ # Storybook configuration
|
|
169
|
-
├── __mocks__/ # Jest mocks
|
|
170
|
-
└── dist/ # Built component library
|
|
171
|
-
```
|
|
172
|
-
|
|
173
|
-
## Components
|
|
174
|
-
|
|
175
|
-
The library includes a comprehensive set of components for building Portland.gov pages:
|
|
176
|
-
|
|
177
|
-
### Navigation Components
|
|
178
|
-
|
|
179
|
-
- **Banner** - Official government website banner
|
|
180
|
-
- **Header** - Generic USWDS Header wrapper with optional extended layout and navigation slots
|
|
181
|
-
- **PGOVHeader** - Portland.gov navigation component based on USWDS Header
|
|
182
|
-
- **Footer** - Site footer with accessibility information
|
|
183
|
-
- **Identifier** - Agency identifier component displaying parent agency and required policy links
|
|
184
|
-
- **SkipNav** - Keyboard accessibility enhancement
|
|
185
|
-
- **SideNav** - Side navigation component
|
|
186
|
-
- **Breadcrumbs** - Navigation breadcrumbs component
|
|
187
|
-
- **Pagination** - USWDS-compliant pagination for navigating paginated content
|
|
188
|
-
|
|
189
|
-
### Interactive Components
|
|
190
|
-
|
|
191
|
-
- **Accordion** - Expandable content sections with multiple variants
|
|
192
|
-
- **Button** - Button components
|
|
193
|
-
- **ButtonGroup** - Group of related buttons, with default and segmented variants
|
|
194
|
-
- **Dropdown** - Accessible custom dropdown/select component
|
|
195
|
-
- **Modal** - Accessible modal dialog component
|
|
196
|
-
- **Tag** - Tag component for labeling and categorization
|
|
197
|
-
|
|
198
|
-
### Layout Components
|
|
199
|
-
|
|
200
|
-
- **PageTemplate** - Complete page template with Banner, PGOVHeader, Footer, and SkipNav
|
|
201
|
-
- **HeroGlobal** - Global hero section with image and call-to-action
|
|
202
|
-
- **HeroHomepage** - Homepage hero section with search and popular links
|
|
203
|
-
- **SummaryBox** - Summary information display
|
|
204
|
-
- **Card** - Card component for displaying content
|
|
205
|
-
- **CardFlag** - Card component with media and content layout
|
|
206
|
-
- **CardGrid** - Grid layout for Card components
|
|
207
|
-
|
|
208
|
-
### Form Components
|
|
209
|
-
|
|
210
|
-
- **Search** - Search input component with variants
|
|
211
|
-
- **TextArea** - Text area component for multi-line text input
|
|
212
|
-
- **TextInput** - Text input component with validation and states
|
|
213
|
-
- **RadioButtons** - Accessible radio button component with multiple variants
|
|
214
|
-
- **Checkbox** - Checkbox component allowing users to select one or more options from a list
|
|
215
|
-
- **LanguageSelector** - Language selection dropdown for switching site language, with accessibility and theme support
|
|
216
|
-
|
|
217
|
-
### Content Components
|
|
218
|
-
|
|
219
|
-
- **Typography** - Text components and styles
|
|
220
|
-
- **Alert** - Alert messages and notifications
|
|
221
|
-
- **Contacts** - Contact information display
|
|
222
|
-
- **Person** - Profile block for individuals with avatar, name, role, department, contact actions, meta, and tags
|
|
223
|
-
- **ProcessSteps** - Process step indicators
|
|
224
|
-
- **StepIndicator** - Horizontal step indicator for multi-step processes
|
|
225
|
-
- **Tooltip** - Tooltip component
|
|
226
|
-
- **PopoverWithCard** - Popover for displaying interactive Card content
|
|
227
|
-
- **Table** - Table component for displaying tabular data with sorting, striping, sticky headers, scrollable and stacked (responsive) layouts.
|
|
228
|
-
|
|
229
|
-
### Design System Components
|
|
230
|
-
|
|
231
|
-
- **ColorSwatch** - Color display and documentation
|
|
232
|
-
- **Spacing** - Spacing utilities and documentation
|
|
233
|
-
|
|
234
|
-
## Documentation
|
|
235
|
-
|
|
236
|
-
Full documentation is available in Storybook:
|
|
237
|
-
|
|
238
|
-
1. Start Storybook with `pnpm run storybook`
|
|
239
|
-
2. Open [http://localhost:6006](http://localhost:6006)
|
|
240
|
-
3. Browse components in the sidebar
|
|
241
|
-
|
|
242
|
-
Key documentation sections:
|
|
243
|
-
|
|
244
|
-
- Introduction - Overview and getting started
|
|
245
|
-
- Components - Detailed documentation for each component
|
|
246
|
-
- Design Tokens - Typography, colors, and spacing
|
|
247
|
-
- Theme Support - Light and dark mode support
|
|
248
|
-
- Color System - Comprehensive color palettes
|
|
249
|
-
|
|
250
|
-
## Design System
|
|
251
|
-
|
|
252
|
-
This component library uses the PGOV theme based on the Portland.gov design system, with design tokens managed in a separate project at [github.com/eGovPDX/design-tokens](https://github.com/eGovPDX/design-tokens).
|
|
253
|
-
|
|
254
|
-
Features:
|
|
255
|
-
|
|
256
|
-
- Built on USWDS (U.S. Web Design System)
|
|
257
|
-
- Accessible by default
|
|
258
|
-
- Responsive design
|
|
259
|
-
- Dark mode support
|
|
260
|
-
- Comprehensive design tokens
|
|
261
|
-
|
|
262
|
-
## Contributing
|
|
263
|
-
|
|
264
|
-
1. Fork the repository
|
|
265
|
-
2. Create a feature branch
|
|
266
|
-
3. Make your changes
|
|
267
|
-
4. Submit a pull request
|
|
268
|
-
|
|
269
|
-
Please ensure your changes:
|
|
39
|
+
Storybook runs on port `6006`, and stories live right alongside the components
|
|
40
|
+
they document. Tests run through Vitest with Playwright for browser-based
|
|
41
|
+
checks.
|
|
270
42
|
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
- Pass all CI checks
|
|
43
|
+
When you add or change a component, keep its behavior, accessibility, styles,
|
|
44
|
+
story, and tests moving together as one unit, and reach for the shared types and
|
|
45
|
+
CSS packages instead of duplicating values locally.
|
|
275
46
|
|
|
276
47
|
## License
|
|
277
48
|
|
|
278
|
-
|
|
49
|
+
MIT
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
@layer properties{@supports (((-webkit-hyphens:none)) and (not (margin-trim:inline))) or ((-moz-orient:inline) and (not (color:rgb(from red r g b)))){*,:before,:after{--tw-border-style:solid;--tw-leading:initial;--tw-font-weight:initial;--tw-tracking:initial}::backdrop{--tw-border-style:solid;--tw-leading:initial;--tw-font-weight:initial;--tw-tracking:initial}}}@layer components{.alert{border-left-style:var(--tw-border-style);border-left-width:var(--border-width-xl,.5rem);padding:var(--spacing-md,1rem);align-items:flex-start;gap:var(--spacing-md,1rem);display:flex}.alert.alert--slim{gap:var(--spacing-xs,.5rem);padding-inline:var(--spacing-md,1rem);padding-block:var(--spacing-xs,.5rem)}.alert .alert__icon{width:var(--spacing-3xl,2.5rem);height:var(--spacing-3xl,2.5rem);padding:var(--spacing-2xs,.25rem)}.alert--slim :is(.alert .alert__icon){width:var(--spacing-xl,1.5rem);height:var(--spacing-xl,1.5rem);padding:var(--spacing-3xs,.125rem)}.alert .alert__content{flex-grow:1}.alert .alert__heading{font-size:var(--text-heading-md,.976875rem);--tw-leading:var(--leading-heading-md,1.5rem);line-height:var(--leading-heading-md,1.5rem);--tw-font-weight:var(--font-weight-bold,700);font-weight:var(--font-weight-bold,700);--tw-tracking:0%;letter-spacing:0%;margin-block:var(--spacing-none,0)}.alert--slim :is(.alert .alert__heading){display:none}.alert .alert__text{font-size:var(--text-body-md,.976875rem);--tw-leading:var(--leading-body-md,1.5rem);line-height:var(--leading-body-md,1.5rem);--tw-tracking:0%;letter-spacing:0%}.alert .alert__text p+p{margin-top:var(--spacing-sm,.75rem)}.alert .alert__close{padding:var(--spacing-3xs,.125rem);cursor:pointer;font-size:20px}}@property --tw-border-style{syntax:"*";inherits:false;initial-value:solid}@property --tw-leading{syntax:"*";inherits:false}@property --tw-font-weight{syntax:"*";inherits:false}@property --tw-tracking{syntax:"*";inherits:false}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import { AlertProps } from '@cityofportland/types/alert';
|
|
2
|
+
import { default as React } from 'react';
|
|
3
|
+
import { ReactBoxProps } from '../box/box';
|
|
4
|
+
export type ReactAlertProps = React.PropsWithChildren<AlertProps & ReactBoxProps & {
|
|
5
|
+
onDismiss: (element: Element) => void;
|
|
6
|
+
}>;
|
|
7
|
+
export declare const AlertContent: React.FC<React.PropsWithChildren<ReactBoxProps>>;
|
|
8
|
+
export declare const AlertDescription: React.FC<React.PropsWithChildren<ReactBoxProps>>;
|
|
9
|
+
export declare const AlertIcon: React.FC<React.PropsWithChildren<ReactBoxProps>>;
|
|
10
|
+
export declare const AlertTitle: React.FC<React.PropsWithChildren<ReactBoxProps>>;
|
|
11
|
+
export declare const Alert: React.FC<ReactAlertProps>;
|