@papillonarts/components 0.38.0 → 0.40.0

package/build/Modern/Pagination/__tests__/Pagination.doc.md

@@ -1,12 +1,94 @@
-# Pagination
+# Features
 
-> Pagination component all features
+```
+Pagination all props and variants
+```
+
+## Props
+
+```typescript
+export type PaginationProps = {
+  className?: string
+  pageCount: number
+  currentPage: number
+  onPageChange?: (e: React.MouseEvent, n: number) => void
+  hrefBuilder?: (n: number) => string
+  marginPageCount?: number
+  showPages?: boolean | ResponsiveValue<boolean>
+  surroundingPageCount?: number
+  renderPage?: (props: PageProps) => React.ReactNode
+}
+```
+
+## Variants
+
+```
+Default
+
+LargerPageCountMargin
+
+HidePageNumbers
+
+HidePageNumbersByViewport
+
+HigherSurroundingPageCount
+
+RenderLinks
+```
+
+### Default
+
+> Pagination default variant
+
+```tsx
+<Pagination pageCount={15} currentPage={2} onPageChange={(e) => e.preventDefault()} showPages={{ narrow: false }} />
+```
+
+### Larger PageCount Margin
+
+> Pagination larger page count margin variant
 
+```tsx
+<Pagination pageCount={15} currentPage={5} marginPageCount={4} onPageChange={(e) => e.preventDefault()} />
 ```
-# Featues
 
-> Defaults
-> LargerPageCountMargin
-> HidePageNumbers, HidePageNumbersByViewport, HigherSurroundingPageCount
-> RenderLinks
+### Hide Page Numbers
+
+> Pagination hide page numbers variant
+
+```tsx
+<Pagination pageCount={15} currentPage={5} showPages={false} onPageChange={(e) => e.preventDefault()} />
+```
+
+### Hide Page Numbers By Viewport
+
+> Pagination hide page numbers by viewport variant
+
+```tsx
+<Pagination pageCount={15} currentPage={5} showPages={{ narrow: false }} onPageChange={(e) => e.preventDefault()} />
+      <p>Page numbers are hidden on narrow viewports.</p>
+```
+
+### Higher Surrounding Page Count
+
+> Pagination higher surrounding page count variant
+
+```tsx
+<Pagination pageCount={15} currentPage={5} surroundingPageCount={4} onPageChange={(e) => e.preventDefault()} />
+```
+
+### Render Links
+
+> Pagination render links variant
+
+```tsx
+<Pagination
+  pageCount={15}
+  currentPage={page}
+  onPageChange={(e, n) => {
+    e.preventDefault()
+    setPage(n)
+  }}
+  renderPage={({ number, ...props }) => <ReactRouterLikeLink to={`#${number}`} {...props} />}
+/>
 ```

package/build/Modern/index.d.ts

@@ -1,4 +1,4 @@
-import '@papillonarts/css/build/primer/index.scss';
+import '@papillonarts/css/index.scss';
 import { Pagination } from './Pagination';
 export type { FlashProps } from './Flash';
 export type { LinkProps } from './Link';

package/build/Modern/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Modern/index.ts"],"names":[],"mappings":"AAAA,OAAO,2CAA2C,CAAA;AAGlD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAEzC,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACzC,YAAY,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;AACvC,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAEnD,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;CAUlB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Modern/index.ts"],"names":[],"mappings":"AAAA,OAAO,8BAA8B,CAAA;AAGrC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAEzC,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACzC,YAAY,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;AACvC,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAEnD,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;CAUlB,CAAA"}

package/build/Modern/index.js

@@ -4,7 +4,7 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.Modern = void 0;
-require("@papillonarts/css/build/primer/index.scss");
+require("@papillonarts/css/index.scss");
 var _Flash = require("./Flash");
 var _Link = require("./Link");
 var _Pagination = require("./Pagination");

package/build/__tests__/README.md

@@ -0,0 +1,159 @@
+# Test Environment
+
+## Date Handling
+
+All tests use UTC timezone with ISO-like formatting to prevent snapshot drift across different environments and timezones.
+
+Date.prototype methods are patched in [jest.setup.js](../../../../jest.setup.js) to ensure deterministic output:
+- `toLocaleString()` → "yyyy-MM-ddTHH:mm:ssZ" (ISO-like, explicit UTC)
+- `toLocaleDateString()` → "yyyy-MM-dd"
+- `toLocaleTimeString()` → "HH:mm:ssZ"
+
+**Example:**
+```javascript
+new Date('2020-07-05T19:04:15Z').toLocaleString() // "2020-07-05T19:04:15Z"
+```
+
+## Test Scripts
+
+- **`npm test`** - Fast parallel execution (no coverage, no snapshot updates)
+  - Best for: Local development, quick feedback
+  - Workers: 50% of CPU cores
+  - Duration: ~49s
+
+- **`npm run test:ci`** - Full CI run (serial, coverage, updates snapshots)
+  - Best for: CI/CD, pre-commit validation, snapshot updates
+  - Workers: 1 (--runInBand for determinism)
+  - Duration: ~97s
+
+- **`npm run test:coverage`** - Parallel with coverage
+  - Best for: Coverage reports without snapshot updates
+  - Workers: 50% of CPU cores
+  - Duration: ~49s
+
+- **`npm run test:tdd`** - Watch mode for local development
+  - Best for: Test-driven development
+  - Features: Watch mode, verbose output, only changed files
+
+- **`npm run test:update-snapshots`** - Update snapshots only
+  - Best for: Intentional snapshot updates without full CI run
+
+- **`npm run test:generate-output`** - Generate JSON output for Storybook
+  - Best for: Storybook integration
+
+## Test Structure
+
+```
+packages/components/src/
+├── Legacy/
+│   ├── Button/
+│   │   ├── __tests__/
+│   │   │   ├── Button.test.ts       # Test file
+│   │   │   └── __snapshots__/       # Snapshot files
+│   │   └── Button.tsx
+│   └── ...
+├── Modern/
+│   └── ...
+└── __tests__/
+    ├── README.md        # This file
+    └── test-utils.ts    # Shared test utilities
+```
+
+## Test Conventions
+
+- **Test files**: `*.test.ts` or `*.test.tsx`
+- **Snapshot files**: Stored in `__snapshots__/` directories
+- **Test utilities**: Shared helpers in `__tests__/test-utils.ts`
+
+## Coverage Thresholds
+
+Thresholds reflect the broader instrumentation baseline and are enforced only in CI or when explicitly enabled.
+
+| Metric      | Threshold | Rationale                                    |
+|-------------|-----------|----------------------------------------------|
+| Statements  | 63%       | Broader scope including library/lodash       |
+| Branches    | 60%       | Accounts for untested conditional paths      |
+| Functions   | 52%       | Library barrels and type-only exports        |
+| Lines       | 64%       | Matches statements threshold                 |
+
+Enforcement:
+- Local fast dev (`npm test`): thresholds not enforced.
+- Local CI-style (`COVERAGE=true npm run test:ci`): thresholds enforced.
+- CI (`CI=true npm run test:ci`): thresholds enforced.
+
+## Running Tests
+
+### Quick Development Cycle
+```bash
+npm test                    # Fast feedback
+npm run test:tdd           # Watch mode
+```
+
+### Before Committing
+```bash
+npm run test:ci            # Full validation with coverage
+```
+
+### Updating Snapshots
+```bash
+npm run test:update-snapshots   # Update snapshots only
+npm run test:ci                 # Update + coverage
+```
+
+## Shared Test Utilities
+
+Use helpers from `test-utils.ts` to reduce boilerplate:
+
+```typescript
+import { renderSnapshot, renderSnapshotAsync } from '../__tests__/test-utils'
+
+// Synchronous snapshot
+test('must match defaults()', () => {
+  renderSnapshot(defaults())
+})
+
+// Async snapshot
+test('must match async()', async () => {
+  await renderSnapshotAsync(async())
+})
+```
+
+## Troubleshooting
+
+### Snapshot Drift
+If snapshots keep changing:
+1. Verify UTC timezone is set (`process.env.TZ = 'UTC'` in jest.setup.js)
+2. Check date formatting functions are using UTC methods (`getUTCDate()`, not `getDate()`)
+3. Run `npm run test:ci` to update snapshots with deterministic settings
+
+### Coverage Threshold Failures
+- Local `npm test` does not enforce thresholds; use it for fast development.
+- Use `COVERAGE=true npm run test:ci` to enforce thresholds locally before CI.
+- Coverage thresholds are enforced in CI to maintain code quality.
+
+### Slow Test Execution
+- Use `npm test` instead of `npm run test:ci` for development (2x faster)
+- Use `npm run test:tdd` to run only changed tests
+- Check for heavy setup/teardown in `beforeEach`/`afterEach` hooks
+
+## CI/CD Integration
+
+For CI pipelines, always use:
+```bash
+CI=true npm run test:ci
+```
+
+This ensures:
+- Serial execution for deterministic results
+- Coverage reports for Codecov
+- Snapshot updates are captured
+- Coverage thresholds are enforced
+- Consistent timing measurements
+
+## Shared Utilities
+
+Import helpers from this folder to reduce boilerplate:
+
+```ts
+import { renderSnapshot, renderSnapshotAsync, waitFor } from './test-utils'
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papillonarts/components",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "description": "Papillon Arts Components",
   "homepage": "https://github.com/papillonarts/papillonarts/tree/master/packages/components",
   "repository": {
@@ -26,8 +26,8 @@
     "build-release": "npm run build"
   },
   "dependencies": {
-    "@papillonarts/css": "^0.38.0",
-    "@papillonarts/library": "^0.38.0"
+    "@papillonarts/css": "^0.40.0",
+    "@papillonarts/library": "^0.40.0"
   },
-  "gitHead": "af44ef015fbdee8b28e2dfbe647d8587e4307ce6"
+  "gitHead": "7a19d357d33591ad460a6cb42f18963082beffd8"
 }