Skip to content

Commit 8db765e

Browse files
PignaPigna
committed
Limit publish files
Limit what is pushed to the ZIP package on publish and add a readme for the package.
1 parent 3d72fa0 commit 8db765e

3 files changed

Lines changed: 239 additions & 0 deletions

File tree

‎.gitattributes‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Exclude development-only files and folders from Git release archives (git archive / GitHub ZIP).
2+
# These are not needed by consumers of the package.
3+
4+
# AI / agent tooling
5+
.agents/ export-ignore
6+
.claude/ export-ignore
7+
8+
# GitHub config (CI, Copilot instructions)
9+
.github/ export-ignore
10+
11+
# Storybook
12+
.storybook/ export-ignore
13+
14+
# Editor / IDE config
15+
.editorconfig export-ignore
16+
.idea/ export-ignore
17+
18+
# Linting, formatting, styling config
19+
.prettierignore export-ignore
20+
.prettierrc export-ignore
21+
.stylelintrc.json export-ignore
22+
eslint.config.js export-ignore
23+
24+
# Impeccable styling tool
25+
.impeccable.md export-ignore
26+
27+
# npm config (consumers have their own)
28+
.npmrc export-ignore
29+
package-lock.json export-ignore
30+
31+
# Git config
32+
.gitignore export-ignore
33+
.gitattributes export-ignore
34+
35+
# Source code (consumers use the built dist/)
36+
src/ export-ignore
37+
38+
# TypeScript config (only needed for development)
39+
tsconfig.json export-ignore
40+
tsconfig.app.json export-ignore
41+
tsconfig.node.json export-ignore
42+
tsconfig.test.json export-ignore
43+
44+
# Build tool config
45+
vite.config.ts export-ignore
46+
vitest.config.ts export-ignore
47+
48+
# Skills / lock files
49+
skills-lock.json export-ignore
50+
51+
# Component documentation (not needed for consumption)
52+
COMPONENTS.md export-ignore
53+
54+
# Repo README (PACKAGE.md is the consumer-facing readme)
55+
README.md export-ignore
56+
57+

‎.github/workflows/publish.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,9 @@ jobs:
4343
- name: Build
4444
run: npm run build
4545

46+
- name: Use package README
47+
run: cp PACKAGE.md README.md
48+
4649
- name: Publish to GitHub Packages
4750
run: npm publish
4851
env:

‎PACKAGE.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# @pigna/component-library
2+
3+
A generic, accessible React component library with dark/light theme support.
4+
5+
Built with **React 19**, **TypeScript**, and **SCSS Modules**.
6+
7+
## Features
8+
9+
- **WCAG 2.2 AA compliant** — semantic HTML, ARIA attributes, keyboard navigation, and color contrast out of the box
10+
- **Dark & light mode** — CSS custom properties with `data-theme` attribute switching
11+
- **Fully themeable** — override any visual decision through CSS custom properties
12+
- **Tree-shakeable** — ESM and CJS output with per-component imports
13+
- **Fully typed** — TypeScript declarations included
14+
15+
## Prerequisites
16+
17+
- **React** `^19.2.4`
18+
- **React DOM** `^19.2.4`
19+
- Node.js **>=20.19.0** or **>=22.12.0**
20+
21+
## Installation
22+
23+
Since this package is hosted on **GitHub Packages**, configure your project's `.npmrc` first:
24+
25+
```ini
26+
@pigna:registry=https://npm.pkg.github.com
27+
//npm.pkg.github.com/:_authToken=${NPM_TOKEN}
28+
```
29+
30+
Set the `NPM_TOKEN` environment variable to a GitHub Personal Access Token with `read:packages` scope, then install:
31+
32+
```bash
33+
npm install @pigna/component-library
34+
```
35+
36+
## Quick Start
37+
38+
```tsx
39+
// Import global styles (reset + design tokens) — do this once in your app entry
40+
import '@pigna/component-library/styles';
41+
// Import components
42+
import { Button } from '@pigna/component-library';
43+
44+
function App() {
45+
return (
46+
<Button variant="primary" size="md" onClick={() => alert('Clicked!')}>
47+
Click me
48+
</Button>
49+
);
50+
}
51+
```
52+
53+
## Theming
54+
55+
The library supports three theming modes:
56+
57+
### Automatic (OS preference)
58+
59+
Works out of the box. If the user's OS is set to dark mode, components render in dark mode automatically.
60+
61+
### Manual override
62+
63+
Set `data-theme` on `<html>` to force a specific theme:
64+
65+
```html
66+
<html data-theme="dark" lang="en-GB">
67+
<html data-theme="light" lang="en-GB">
68+
```
69+
70+
### JavaScript toggle
71+
72+
```ts
73+
document.documentElement.setAttribute('data-theme', 'dark'); // Force dark
74+
document.documentElement.setAttribute('data-theme', 'light'); // Force light
75+
document.documentElement.removeAttribute('data-theme'); // Follow OS
76+
```
77+
78+
### Custom tokens
79+
80+
All visual decisions flow through CSS custom properties. Override them in your own stylesheet to match your brand:
81+
82+
```css
83+
:root {
84+
--color-primary: #0066cc;
85+
--color-primary-hover: #0052a3;
86+
--radius-md: 6px;
87+
/* ... */
88+
}
89+
```
90+
91+
## Available Components
92+
93+
### Layout & Navigation
94+
95+
| Component | Description |
96+
|---|---|
97+
| `Breadcrumb` | Navigation breadcrumb trail with `BreadcrumbItem` children |
98+
| `HamburgerMenu` | Collapsible mobile navigation menu |
99+
| `MenuItem` | Clickable navigation item |
100+
| `MenuItemGroup` | Grouped collection of menu items |
101+
| `SideMenu` | Sidebar navigation container |
102+
| `Tabs` | Tabbed interface with `TabList`, `Tab`, and `TabPanel` |
103+
104+
### Actions
105+
106+
| Component | Description |
107+
|---|---|
108+
| `Button` | Primary action element with `primary`, `secondary`, `tertiary`, and `danger` variants |
109+
| `CloseButton` | Accessible close/dismiss button |
110+
| `TextLink` | Styled anchor link |
111+
112+
### Feedback
113+
114+
| Component | Description |
115+
|---|---|
116+
| `Banner` | Inline notification banner (`info`, `success`, `warning`, `error`) |
117+
| `Dialog` | Modal dialog with focus trapping |
118+
| `ConfirmPopover` | Confirmation prompt in a popover |
119+
| `NotificationPopup` | Toast notification with auto-dismiss |
120+
| `NotificationToastContainer` | Container for stacking toast notifications |
121+
| `Popover` | Floating content anchored to a trigger |
122+
| `ProgressIndicator` | Progress bar / indicator |
123+
| `Spinner` | Loading spinner |
124+
| `SkeletonLoader` | Placeholder skeleton for loading states |
125+
126+
### Data Display
127+
128+
| Component | Description |
129+
|---|---|
130+
| `NotificationBadge` | Numeric badge for unread counts |
131+
| `ProfilePicture` | Avatar with optional status indicator |
132+
| `Table` | Data table with sorting support |
133+
| `Tag` | Label tag / chip |
134+
135+
### Form
136+
137+
| Component | Description |
138+
|---|---|
139+
| `FormField` | Field wrapper with label, description, and error messaging |
140+
| `FormGroup` | Groups related form fields |
141+
| `FormSection` | Titled section within a form |
142+
| `Input` | Text input field |
143+
| `Textarea` | Multi-line text input |
144+
| `Select` | Dropdown select |
145+
| `Checkbox` | Checkbox input |
146+
| `RadioGroup` | Radio button group |
147+
| `Toggle` | Toggle switch |
148+
| `ConditionalField` | Conditionally visible form field |
149+
150+
### Utilities
151+
152+
| Export | Description |
153+
|---|---|
154+
| `ComponentLibraryProvider` | Localization provider for overriding built-in strings |
155+
156+
### Icons
157+
158+
`ChevronDownIcon` · `ChevronLeftIcon` · `ChevronRightIcon` · `CloseIcon` · `ErrorIcon` · `FolderIcon` · `HamburgerIcon` · `InfoIcon` · `SortAscIcon` · `SortDescIcon` · `SortNeutralIcon` · `SuccessIcon` · `WarningIcon`
159+
160+
## Localization
161+
162+
Wrap your app in `ComponentLibraryProvider` to override built-in strings:
163+
164+
```tsx
165+
import { ComponentLibraryProvider } from '@pigna/component-library';
166+
167+
<ComponentLibraryProvider strings={{ dialog: { close: 'Sluiten' } }}>
168+
<App />
169+
</ComponentLibraryProvider>
170+
```
171+
172+
## Browser Support
173+
174+
Chrome, Edge, Firefox, and Safari (last 2 versions).
175+
176+
## License
177+
178+
MIT
179+

0 commit comments

Comments
 (0)