@papillonarts/components 0.39.0 → 0.40.0

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

@@ -1,11 +1,156 @@
-# Flash
+# Features
 
-> Flash component all features
+```
+Flash all props and variants
+```
+
+## Props
+
+```typescript
+export type FlashProps = ComponentPropsWithoutRef<'div'> & {
+  className?: string
+  variant?: 'default' | 'warning' | 'success' | 'danger'
+  full?: boolean
+}
+```
+
+## Variants
+
+```
+Default
+
+Success
+
+Danger
 
+Warning
+
+Full
+
+WithIconAndAction
+
+WithIconActionDismiss
+```
+
+### Default
+
+> Flash default variant
+
+```tsx
+<Flash>Default</Flash>
 ```
-# Featues
 
-> Default
-> Success, Danger, Warning, Full
-> WithIconAndAction, WithIconActionDismiss
+### Success
+
+> Flash success variant
+
+```tsx
+<Flash
+  variant="success"
+  style={{
+    display: 'grid',
+    gridTemplateColumns: 'min-content 1fr minmax(0, auto)',
+    gridTemplateAreas: `'visual message actions'`,
+  }}
+>
+  <div className={classes.Visual}>
+    <CheckCircleIcon aria-label="Success" />
+  </div>
+  <div className={classes.Message}>Success</div>
+</Flash>
+```
+
+### Danger
+
+> Flash danger variant
+
+```tsx
+<Flash
+  variant="danger"
+  style={{
+    display: 'grid',
+    gridTemplateColumns: 'min-content 1fr minmax(0, auto)',
+    gridTemplateAreas: `'visual message actions'`,
+  }}
+>
+  <div className={classes.Visual}>
+    <InfoIcon aria-label="Danger" />
+  </div>
+  <div className={classes.Message}>Danger</div>
+</Flash>
+```
+
+### Warning
+
+> Flash warning variant
+
+```tsx
+<Flash
+  variant="warning"
+  style={{
+    display: 'grid',
+    gridTemplateColumns: 'min-content 1fr minmax(0, auto)',
+    gridTemplateAreas: `'visual message actions'`,
+  }}
+>
+  <div className={classes.Visual}>
+    <AlertIcon aria-label="Warning" />
+  </div>
+  <div className={classes.Message}>Warning</div>
+</Flash>
+```
+
+### Full
+
+> Flash full variant
+
+```tsx
+<Flash
+  full
+  style={{
+    display: 'grid',
+    gridTemplateColumns: 'min-content 1fr minmax(0, auto)',
+    gridTemplateAreas: `'visual message actions'`,
+  }}
+>
+  <div className={classes.Visual}>
+    <InfoIcon aria-label="Info" />
+  </div>
+  <div className={classes.Message}>Full</div>
+</Flash>
+```
+
+### With Icon And Action
+
+> Flash with icon and action variant
+
+```tsx
+<Flash className={classes.WithIconAndAction}>
+  <div className={classes.Visual}>
+    <InfoIcon aria-label="Info" />
+  </div>
+  <div className={classes.Message}>
+    This is a flash message with an icon and an action.
+    <Link href="/"> Learn more.</Link>
+  </div>
+  <div className={classes.ActionsResponsive}>{/*<Button>Join waitlist</Button>*/}</div>
+</Flash>
+```
+
+### With Icon Action Dismiss
+
+> Flash with icon action dismiss variant
+
+```tsx
+<Flash className={classes.WithIconActionDismiss}>
+  <div className={classes.Visual}>
+    <InfoIcon aria-label="Info" />
+  </div>
+  <div className={classes.Message}>
+    This is a flash message with an icon and an action.
+    <Link href="/"> Learn more.</Link>
+  </div>
+  <div className={classes.ActionsResponsive}>{/*<Button>Join waitlist</Button>*/}</div>
+  <div className={classes.Close}>{/*<IconButton variant="invisible" icon={XIcon} aria-label="Dismiss" />*/}</div>
+</Flash>
 ```

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

@@ -1,10 +1,96 @@
-# Link
+# Features
 
-> Link component all features
+```
+Link all props and variants
+```
+
+## Props
+
+```typescript
+type StyledLinkProps<As extends ElementType = 'a'> = {
+  as?: As
+  /** @deprecated use CSS modules to style hover color */
+  hoverColor?: string
+  muted?: boolean
+  // Link inside a text block
+  inline?: boolean
+}
+```
+
+## Variants
+
+```
+Default
+
+Muted
+
+Inline1
+
+Inline2
+```
 
+### Default
+
+> Link default variant
+
+```tsx
+<Link href="#">Links are great</Link>
+```
+
+### Muted
+
+> Link muted variant
+
+```tsx
+<Link href="#" muted>
+  Link
+</Link>
 ```
-# Featues
 
-> Default
-> Muted, Inline1, Inline2
+### Inline1
+
+> Link inline 1 variant
+
+```tsx
+<Link inline={true} href="#">
+  Link
+</Link>
+```
+
+### Inline2
+
+> Link inline 2 variant
+
+```tsx
+<div>
+  <div style={{ display: 'flex', flexDirection: 'column' }} data-a11y-link-underlines="true">
+    [data-a11y-link-underlines=true] (inline links have underline)
+    <Link href="#">inline: undefined</Link>
+    <Link inline={true} href="#">
+      inline: true
+    </Link>
+    <Link inline={false} href="#">
+      inline: false
+    </Link>
+    <br />
+    <Link muted={true} inline={true} href="#">
+      inline: true, muted: true
+    </Link>
+  </div>
+  <br />
+  <div style={{ display: 'flex', flexDirection: 'column' }} data-a11y-link-underlines="false">
+    [data-a11y-link-underlines=false] (inline has no effect)
+    <Link href="#">inline: undefined</Link>
+    <Link inline={true} href="#">
+      inline: true
+    </Link>
+    <Link inline={false} href="#">
+      inline: false
+    </Link>
+    <br />
+    <Link muted={true} inline={true} href="#">
+      inline: true, muted: true
+    </Link>
+  </div>
+</div>
 ```

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/__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.39.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.39.0",
-    "@papillonarts/library": "^0.39.0"
+    "@papillonarts/css": "^0.40.0",
+    "@papillonarts/library": "^0.40.0"
   },
-  "gitHead": "b8f07f71414d7133bc1cfa967ecf30ebca383ef7"
+  "gitHead": "7a19d357d33591ad460a6cb42f18963082beffd8"
 }