diff --git a/.changeset/config.json b/.changeset/config.json index d88011f..2be13d4 100644 --- a/.changeset/config.json +++ b/.changeset/config.json @@ -4,7 +4,7 @@ "commit": false, "fixed": [], "linked": [], - "access": "restricted", + "access": "public", "baseBranch": "main", "updateInternalDependencies": "patch", "ignore": [] diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index b96fd16..66f0e10 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -83,7 +83,8 @@ 3000, // Storybook 5173, // Vite dev server 4173, // Vite preview - 8080 // API server + 8080, // API server + 9323 // Playwright UI mode ], // Use 'postCreateCommand' to run commands after the container is created diff --git a/.devcontainer/docker-compose.yml b/.devcontainer/docker-compose.yml index 1e32612..4b25062 100644 --- a/.devcontainer/docker-compose.yml +++ b/.devcontainer/docker-compose.yml @@ -34,13 +34,8 @@ services: # Persist Playwright browsers - playwright-browsers:/home/node/.cache/ms-playwright - # Forward ports for development - ports: - - "3000:3000" # Storybook - - "5173:5173" # Vite dev server - - "4173:4173" # Vite preview - - "8080:8080" # API server - - "9323:9323" # Playwright UI mode + # Note: Port forwarding is handled by VS Code via devcontainer.json forwardPorts + # This prevents port conflicts with other containers on the host machine # Keep container running command: sleep infinity diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index e64f752..4b0f049 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -101,7 +101,10 @@ jobs: .private = false | .publishConfig.registry = "https://npm.pkg.github.com" | .repository.type = "git" | - .repository.url = $repo_url' \ + .repository.url = $repo_url | + .scripts = {} | + del(.devDependencies) | + del(.size-limit)' \ package.json > package.json.tmp && mv package.json.tmp package.json echo "Updated package.json for publishing:" @@ -118,6 +121,44 @@ jobs: env: NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + - name: Setup Node.js for npm registry + uses: actions/setup-node@v4 + with: + node-version: 20 + registry-url: "https://registry.npmjs.org" + + - name: Update package.json for npm registry + run: | + VERSION="${{ steps.version.outputs.version }}" + VERSION_NO_V=${VERSION#v} + + cd packages/ui-kit + + # Update package.json for npm registry publishing + jq --arg name "@etherisc/ui-kit" \ + --arg version "${VERSION_NO_V}" \ + --arg repo_url "git+https://github.com/${{ github.repository }}.git" \ + '.name = $name | + .version = $version | + .private = false | + del(.publishConfig) | + .repository.type = "git" | + .repository.url = $repo_url | + .scripts = {} | + del(.devDependencies) | + del(.size-limit)' \ + package.json > package.json.tmp && mv package.json.tmp package.json + + echo "Updated package.json for npm registry:" + cat package.json | jq '.name, .version, .private, .repository' + + - name: Publish to npm registry + run: | + cd packages/ui-kit + npm publish --access=public + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + - name: Setup Pages uses: actions/configure-pages@v4 with: @@ -177,11 +218,18 @@ jobs: ### 📦 Installation \`\`\`bash + # From npm registry (recommended) npm install @etherisc/ui-kit@${VERSION#v} + # or + pnpm add @etherisc/ui-kit@${VERSION#v} + + # From GitHub Packages (alternative) + npm install @etherisc/ui-kit@${VERSION#v} --registry=https://npm.pkg.github.com \`\`\` ### 🔗 Links - - **Package**: [GitHub Packages](https://github.com/${{ github.repository }}/packages) + - **npm Package**: [npmjs.com](https://www.npmjs.com/package/@etherisc/ui-kit) + - **GitHub Package**: [GitHub Packages](https://github.com/${{ github.repository }}/packages) - **Demo**: [Storybook](${PAGE_URL}) - **Build**: \`${BUILD_HASH}\` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e93ad89..e0cb3ac 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -366,20 +366,31 @@ We use [Changesets](https://github.com/changesets/changesets) for version manage pnpm changeset ``` -2. **Follow the prompts to describe your changes** +2. **Changesets bot creates release PR** -3. **Commit the changeset file** - ```bash - git add .changeset/ - git commit -m "chore: add changeset for feature" - ``` +3. **Review and merge release PR to main** + +4. **Automated release process**: + - Publishes to npm registry (public access) + - Publishes to GitHub Packages + - Creates GitHub release with release notes + - Deploys Storybook to GitHub Pages + +### Publishing Destinations + +The package is automatically published to multiple registries: + +- **npm Registry** (recommended for consumers): `npm install @etherisc/ui-kit` +- **GitHub Packages** (alternative): `npm install @etherisc/ui-kit --registry=https://npm.pkg.github.com` + +### Manual Release (Maintainers Only) -### Release Workflow +For manual releases, use the GitHub Actions workflow: -1. Changesets bot creates release PR -2. Review and merge release PR -3. Automated release to npm and GitHub -4. Storybook deployment to GitHub Pages +1. Go to Actions → Release workflow +2. Click "Run workflow" +3. Enter the version tag (e.g., `v0.3.0-beta`) +4. The workflow will build, test, and publish automatically ## Issue Reporting diff --git a/README.md b/README.md index c1d8932..56f8e73 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,65 @@ React component library and showcase admin app built with modern tools: - 🏗️ Vite + TypeScript + pnpm - 📚 Storybook + Vitest + Playwright +## Installation + +### For Consumers (Using the UI Kit) + +Install the UI kit package in your React project: + +```bash +# From npm registry (recommended) +npm install @etherisc/ui-kit +# or +pnpm add @etherisc/ui-kit +# or +yarn add @etherisc/ui-kit + +# From GitHub Packages (alternative) +npm install @etherisc/ui-kit --registry=https://npm.pkg.github.com +``` + +#### Peer Dependencies + +Make sure you have the required peer dependencies installed: + +```bash +npm install react@>=18.0.0 react-dom@>=18.0.0 +``` + +#### Basic Usage + +```tsx +import { Button, TextInput, AppShell } from "@etherisc/ui-kit"; +import "@etherisc/ui-kit/dist/style.css"; + +function App() { + return ( + +
+

My App

+ + +
+ + ); +} +``` + +#### Available Components + +- **Form Components**: Button, TextInput, NumberInput, Select, Checkbox, RadioGroup, DatePicker +- **Layout Components**: AppShell, AuthShell, MainLayout +- **Data Components**: DataTable with pagination and sorting +- **Feedback Components**: Toast system, StatusBadge, ErrorBoundary +- **Editor Components**: MarkdownEditor, CodeEditor + +For complete documentation and examples, visit our [Storybook](https://etherisc.github.io/ui-kit/). + +## Development Setup + +### For Contributors (Developing the UI Kit) + ## Quick Start ### Option 1: DevContainer (Recommended) diff --git a/docs/task-planning/fix-package-installation-issue-36.md b/docs/task-planning/fix-package-installation-issue-36.md new file mode 100644 index 0000000..3ce614b --- /dev/null +++ b/docs/task-planning/fix-package-installation-issue-36.md @@ -0,0 +1,88 @@ +# Task Planning: Fix Package Installation Issue #36 + +**GitHub Issue**: #36 - Package installation fails when used as dependency - blocks all consumers +**Priority**: HIGH - Critical blocker for all package consumers +**Estimated Duration**: 1-2 days +**Branch**: `fix/package-installation-issue-36` + +## Problem Summary + +The `@etherisc/ui-kit` package cannot be installed as a dependency in consumer projects due to: + +1. Husky prepare script failing in consumer environments +2. Package marked as private preventing npm publishing +3. Monorepo structure confusion for consumers +4. Missing proper peer dependencies configuration + +## Task Breakdown + +| Task Description | DoD (Definition of Done) | Status | +| --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| **1. Fix Husky Prepare Script** - Update root package.json prepare script to be conditional and not fail in consumer environments | Root package.json prepare script runs without error when package is installed as dependency; test installation in sample consumer project succeeds | Complete | +| **2. Make UI Kit Package Publishable** - Remove private flag and configure package.json for npm publishing | packages/ui-kit/package.json has private: false; proper peer dependencies defined; package can be published to npm | Complete | +| **3. Configure npm Publishing** - Update changesets config and GitHub Actions for npm registry publishing | .changeset/config.json updated for public access; GitHub Actions workflow can publish to npm registry; npm publish workflow exists | Complete | +| **4. Optimize Package for Consumers** - Clean up package.json scripts and dependencies for consumer use | Only essential scripts remain in published package.json; dev dependencies properly separated; bundle size optimized | Complete | +| **5. Test Package Installation** - Create test consumer project and verify installation works | Can install via `pnpm add @etherisc/ui-kit`; can install via `pnpm add github:etherisc/ui-kit`; components import and render correctly | Complete | +| **6. Update Documentation** - Add installation instructions and usage examples | README.md includes clear installation instructions; CONTRIBUTING.md updated with publishing workflow | Complete | + +## Technical Implementation Details + +### Phase 1: Immediate Fixes + +- Update root `package.json` prepare script to be conditional +- Remove `"private": true` from ui-kit package.json +- Add proper peer dependencies (React 18+) +- Configure proper package exports + +### Phase 2: Publishing Setup + +- Update changesets configuration for public access +- Configure GitHub Actions for npm publishing +- Test publishing workflow + +### Phase 3: Consumer Optimization + +- Remove development-only scripts from published package +- Ensure proper file inclusion via "files" field +- Optimize bundle for consumer use + +### Phase 4: Testing & Documentation + +- Create sample consumer project for testing +- Test both npm and GitHub installation methods +- Update documentation with installation instructions + +## Expected Outcomes + +After completion: + +- ✅ Consumers can install package without errors +- ✅ Package available on npm registry with proper versioning +- ✅ GitHub installation method also works reliably +- ✅ Reduced installation overhead (no dev dependencies) +- ✅ Clear documentation for consumers + +## Test Criteria + +1. **Installation Test**: `pnpm add @etherisc/ui-kit` completes successfully +2. **GitHub Installation Test**: `pnpm add github:etherisc/ui-kit` completes successfully +3. **Import Test**: Components can be imported: `import { Button } from '@etherisc/ui-kit'` +4. **Build Test**: Consumer project builds successfully with ui-kit components +5. **Runtime Test**: Components render and function correctly in consumer app + +## Dependencies + +- Requires access to npm registry for publishing +- May need GitHub token with package write permissions +- Changesets configuration for version management + +## Risks & Mitigation + +**Risk**: Breaking existing development workflow +**Mitigation**: Test all development commands after changes + +**Risk**: Publishing misconfiguration +**Mitigation**: Test publishing in separate environment first + +**Risk**: Bundle size increase for consumers +**Mitigation**: Verify file inclusion and exclude dev dependencies diff --git a/package.json b/package.json index 414d004..fdd16d0 100644 --- a/package.json +++ b/package.json @@ -14,7 +14,7 @@ "test:a11y:specific": "cd packages/ui-kit && pnpm run test-storybook:specific", "lint": "pnpm -r lint", "format": "prettier --write \"**/*.{ts,tsx,md}\"", - "prepare": "husky install" + "prepare": "node -e \"try { require('fs').existsSync('.git') && require('husky').install() } catch (e) {}\"" }, "devDependencies": { "@changesets/cli": "^2.29.4", diff --git a/packages/ui-kit/package.json b/packages/ui-kit/package.json index 5fcfb67..ccaee9f 100644 --- a/packages/ui-kit/package.json +++ b/packages/ui-kit/package.json @@ -1,7 +1,6 @@ { "name": "@etherisc/ui-kit", "version": "0.2.0-beta", - "private": true, "type": "module", "license": "Apache-2.0", "main": "./dist/ui-kit.umd.cjs", @@ -18,6 +17,10 @@ "files": [ "dist/**" ], + "peerDependencies": { + "react": ">=18.0.0", + "react-dom": ">=18.0.0" + }, "scripts": { "dev": "vite", "build": "tsc && vite build", @@ -65,8 +68,6 @@ "@radix-ui/react-slot": "^1.2.3", "@sentry/browser": "^9.22.0", "@sentry/react": "^9.22.0", - "@testing-library/user-event": "^14.6.1", - "@types/testing-library__jest-dom": "^6.0.0", "class-variance-authority": "^0.7.1", "clsx": "^2.1.1", "cmdk": "^1.1.1", @@ -75,12 +76,9 @@ "dompurify": "^3.2.6", "i18next": "^25.2.1", "i18next-browser-languagedetector": "^8.1.0", - "jsdom": "^26.1.0", "lucide-react": "^0.511.0", "marked": "^15.0.12", - "react": "^19.1.0", "react-day-picker": "8.10.1", - "react-dom": "^19.1.0", "react-hook-form": "^7.56.4", "react-i18next": "^15.5.2", "tailwind-merge": "^2.6.0", @@ -126,11 +124,13 @@ "@testing-library/dom": "^10.0.0", "@testing-library/jest-dom": "^6.6.3", "@testing-library/react": "^16.3.0", + "@testing-library/user-event": "^14.6.1", "@types/dompurify": "^3.2.0", "@types/jest": "^29.5.14", "@types/marked": "^6.0.0", "@types/react": "^19.1.4", "@types/react-dom": "^19.1.5", + "@types/testing-library__jest-dom": "^6.0.0", "@types/testing-library__react": "^10.2.0", "@vitejs/plugin-react": "^4.4.1", "@vitest/coverage-v8": "^1.6.1", @@ -143,6 +143,7 @@ "eslint-plugin-react": "^7.37.5", "eslint-plugin-react-hooks": "^5.2.0", "eslint-plugin-react-refresh": "^0.4.20", + "jsdom": "^26.1.0", "postcss": "^8.5.3", "prop-types": "^15.8.1", "react": "^19.1.0", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 9a29313..6097896 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -309,12 +309,6 @@ importers: '@sentry/react': specifier: ^9.22.0 version: 9.22.0(react@19.1.0) - '@testing-library/user-event': - specifier: ^14.6.1 - version: 14.6.1(@testing-library/dom@10.4.0) - '@types/testing-library__jest-dom': - specifier: ^6.0.0 - version: 6.0.0 class-variance-authority: specifier: ^0.7.1 version: 0.7.1 @@ -339,24 +333,15 @@ importers: i18next-browser-languagedetector: specifier: ^8.1.0 version: 8.1.0 - jsdom: - specifier: ^26.1.0 - version: 26.1.0 lucide-react: specifier: ^0.511.0 version: 0.511.0(react@19.1.0) marked: specifier: ^15.0.12 version: 15.0.12 - react: - specifier: ^19.1.0 - version: 19.1.0 react-day-picker: specifier: 8.10.1 version: 8.10.1(date-fns@4.1.0)(react@19.1.0) - react-dom: - specifier: ^19.1.0 - version: 19.1.0(react@19.1.0) react-hook-form: specifier: ^7.56.4 version: 7.56.4(react@19.1.0) @@ -445,6 +430,9 @@ importers: '@testing-library/react': specifier: ^16.3.0 version: 16.3.0(@testing-library/dom@10.4.0)(@types/react-dom@19.1.5(@types/react@19.1.4))(@types/react@19.1.4)(react-dom@19.1.0(react@19.1.0))(react@19.1.0) + '@testing-library/user-event': + specifier: ^14.6.1 + version: 14.6.1(@testing-library/dom@10.4.0) '@types/dompurify': specifier: ^3.2.0 version: 3.2.0 @@ -460,6 +448,9 @@ importers: '@types/react-dom': specifier: ^19.1.5 version: 19.1.5(@types/react@19.1.4) + '@types/testing-library__jest-dom': + specifier: ^6.0.0 + version: 6.0.0 '@types/testing-library__react': specifier: ^10.2.0 version: 10.2.0(@testing-library/dom@10.4.0)(@types/react-dom@19.1.5(@types/react@19.1.4))(@types/react@19.1.4)(react-dom@19.1.0(react@19.1.0))(react@19.1.0) @@ -496,12 +487,21 @@ importers: eslint-plugin-react-refresh: specifier: ^0.4.20 version: 0.4.20(eslint@9.27.0(jiti@2.4.2)) + jsdom: + specifier: ^26.1.0 + version: 26.1.0 postcss: specifier: ^8.5.3 version: 8.5.3 prop-types: specifier: ^15.8.1 version: 15.8.1 + react: + specifier: ^19.1.0 + version: 19.1.0 + react-dom: + specifier: ^19.1.0 + version: 19.1.0(react@19.1.0) size-limit: specifier: ^11.2.0 version: 11.2.0