@jack.winter/pancake-ui 0.0.0-stage → 0.1.1

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.
Files changed (57) hide show
  1. package/CHANGELOG.md +73 -0
  2. package/LICENSE +21 -0
  3. package/README.md +93 -2
  4. package/dist/components/Button/Button.d.ts +7 -0
  5. package/dist/components/Button/ButtonLink.d.ts +8 -0
  6. package/dist/components/Button/IconButton.d.ts +7 -0
  7. package/dist/components/Checkbox/Checkbox.d.ts +6 -0
  8. package/dist/components/Dialog/Dialog.d.ts +9 -0
  9. package/dist/components/Disclosure/Disclosure.d.ts +17 -0
  10. package/dist/components/DropdownMenu/DropdownMenu.d.ts +25 -0
  11. package/dist/components/DropdownMenu/menuKeyboard.d.ts +3 -0
  12. package/dist/components/FileField/FileField.d.ts +7 -0
  13. package/dist/components/Pagination/Pagination.d.ts +22 -0
  14. package/dist/components/Pagination/paginationPages.d.ts +5 -0
  15. package/dist/components/Popover/Popover.d.ts +7 -0
  16. package/dist/components/RadioGroup/RadioGroup.d.ts +18 -0
  17. package/dist/components/Select/Select.d.ts +9 -0
  18. package/dist/components/Surface/Surface.d.ts +3 -0
  19. package/dist/components/Switch/Switch.d.ts +6 -0
  20. package/dist/components/Table/Table.d.ts +6 -0
  21. package/dist/components/Tabs/Tabs.d.ts +17 -0
  22. package/dist/components/TextField/TextField.d.ts +8 -0
  23. package/dist/components/Textarea/Textarea.d.ts +7 -0
  24. package/dist/components/Tooltip/Tooltip.d.ts +7 -0
  25. package/dist/components/Tooltip/useTooltip.d.ts +12 -0
  26. package/dist/components/feedback/BannerToast.d.ts +8 -0
  27. package/dist/components/feedback/EmptyState.d.ts +8 -0
  28. package/dist/components/feedback/StatusChip.d.ts +6 -0
  29. package/dist/components/identity/Avatar.d.ts +9 -0
  30. package/dist/components/identity/AvatarGroup.d.ts +13 -0
  31. package/dist/components/layout/Inline.d.ts +5 -0
  32. package/dist/components/layout/Stack.d.ts +10 -0
  33. package/dist/components/layout/Text.d.ts +8 -0
  34. package/dist/components/layout/layout.shared.d.ts +16 -0
  35. package/dist/components/navigation/AppHeader.d.ts +11 -0
  36. package/dist/components/navigation/BottomNavigation.d.ts +12 -0
  37. package/dist/components/navigation/SectionHeader.d.ts +11 -0
  38. package/dist/components/navigation/SegmentedControl.d.ts +15 -0
  39. package/dist/components/navigation/StepProgress.d.ts +6 -0
  40. package/dist/components/progress/LoadingIndicator.d.ts +5 -0
  41. package/dist/components/progress/Progress.d.ts +8 -0
  42. package/dist/fonts/Inter-Bold.ttf +0 -0
  43. package/dist/fonts/Inter-Regular.ttf +0 -0
  44. package/dist/fonts/Inter-SemiBold.ttf +0 -0
  45. package/dist/fonts/OFL.txt +92 -0
  46. package/dist/fonts/inter-4.1.provenance.json +41 -0
  47. package/dist/fonts.css +21 -0
  48. package/dist/foundations/tokens.d.ts +168 -0
  49. package/dist/index.d.ts +36 -0
  50. package/dist/index.js +1121 -0
  51. package/dist/styles.css +3 -0
  52. package/dist/theme.css +97 -0
  53. package/docs/components.md +182 -0
  54. package/docs/installation.md +145 -0
  55. package/docs/styling.md +92 -0
  56. package/docs/verification.md +80 -0
  57. package/package.json +107 -4
@@ -0,0 +1,80 @@
1
+ # Verification and component contracts
2
+
3
+ Run `npm ci`, then `npx playwright install chromium firefox webkit`, then `npm run verify`. Verification builds the package and Storybook, installs the archive into consumers, and runs production-browser tests. The macOS CI runner sets `AppleLocale=en_GB` and `AppleLanguages=en-GB` before starting browsers because native date/time formatting also depends on OS preferences; Playwright locale alone is insufficient. Screenshot baselines remain specific to macOS Chromium; see [styling.md](styling.md) before updating them.
4
+
5
+ ## Required evidence for a new component
6
+
7
+ 1. Export the component, add dedicated stories as described below, and include it in `src/stories/comparison/Comparison.stories.tsx` with its visibility marker.
8
+ 2. Add an entry in `tests/component-contracts.json` for semantics, keyboard, state, form behaviour, and refs. Each category points to an assertion-bearing test registered in the matching `src/components/<family>/<Component>.spec.ts`, or gives a reason it does not apply. Semantics always requires a test. The gate rejects missing exports, missing categories, unknown tests, and reuse of tests that do not identify the component.
9
+ 3. Add interaction/state fixtures in `src/stories/contracts/Contracts.stories.tsx`. Test user-observable behaviour: accessible names and roles, keyboard operation, callbacks firing once, controlled and uncontrolled updates, disabled/loading inactivity, form submission/reset, descriptions, and ref targets as applicable.
10
+ 4. Add positive and negative public API examples to `compatibility/types.tsx`. These compile against the installed archive with declaration checking enabled. Keep a descriptive `@ts-expect-error` beside each intentionally invalid call; it must fail compilation if the API accidentally starts accepting that call.
11
+ 5. Run the full suite and inspect visual changes. A contract entry or passing screenshot does not establish that an assertion is meaningful; independent review checks the test's expectations against the component's purpose.
12
+
13
+ Playwright opens the contract and comparison pages with Storybook’s accessibility addon in manual mode when it owns explicit axe scans. This prevents concurrent scans of the same document; normal Storybook usage retains automatic checks. A deliberate unnamed-button probe verifies that the explicit scanner still detects violations.
14
+
15
+ The contracts include explicit axe scans of the comparison and interactive states, plus narrow layout, reduced-motion and forced-colour checks. Automated accessibility scans do not establish screen-reader announcements or complete accessibility conformance. Review new interaction patterns with keyboard and assistive technology.
16
+
17
+ ## What verification runs
18
+
19
+ - Formatting, strict TypeScript, type-aware ESLint for library/tests/configuration (consumer templates receive ordinary lint plus installed-package type checks), style-token checks, and comparison/contract coverage gates.
20
+ - Tests of the gates themselves, including rejection of focused/skipped tests, missing contracts, unawaited assertions, and unexpected browser warnings.
21
+ - Library and Storybook builds, archive contents, and Tailwind theme integration.
22
+ - Installed-package positive and negative type examples with `skipLibCheck: false`.
23
+ - React 19.2.0 (the declared minimum) and the pinned development React version, with matching React DOM versions. Each installed version is asserted before checks run.
24
+ - Node server rendering without a browser environment, then production hydration of the server markup. Browser tests check stable IDs, accessible descriptions, refs, and interactive updates in both versions. This tests ordinary React SSR/hydration; it does not establish framework-specific RSC or Next.js support.
25
+ - Production consumer, behaviour, accessibility, and hydration tests in Chromium, Firefox, and WebKit. Screenshots run only in the canonical Chromium project.
26
+
27
+ On macOS, the pinned Firefox build uses isolated worker-local application-data directories to avoid its documented app-data launch issue. These directories are removed after browser teardown; user browser settings are not changed.
28
+
29
+ Component behaviour specs live beside their components. Shared accessibility/probe, visual, installed-package, and hydration suites remain under `tests/`. All browser specs use `tests/fixtures.ts`, directly or through `tests/contracts-fixture.ts` (which opens the contract story before each test). Unexpected page errors and console errors/warnings fail teardown. Intentional negative probes assert that the same behavioural oracles reject broken activation counts, names, and disabled semantics. They do not suppress normal test failures.
30
+
31
+ Focused tests, skipped tests, and expected-failure tests are prohibited in the verification suites. Retries are disabled, flaky passes fail, and normal runs never update screenshots. A single failed browser or compatibility variant fails the command. Traces and screenshot diffs are retained in `test-results/` for failures.
32
+
33
+ ## Focused commands
34
+
35
+ ```sh
36
+ npm run check:contracts
37
+ npm run test:contracts
38
+ npm run test:verification
39
+ # Requires a package build/archive prepared by test:package:
40
+ npm run check:compatibility
41
+ # After verify has prepared all builds and consumers:
42
+ npx playwright test --project=firefox src/components/Button/Button.spec.ts
43
+ ```
44
+
45
+ Compatibility consumers live under `.tmp/compatibility/` and are rebuilt for each package verification. Installing their dependencies requires registry access. The production app served by the browser tests lives under `.tmp/consumer/dist/`; the browser is not testing Vite's development transforms.
46
+
47
+ ## Protect the evidence
48
+
49
+ Changes to tests, checkers, workflow configuration, contract applicability, or screenshot baselines require independent review, as recorded in `AGENTS.md`. Report which expectations changed and why. Demonstrate that an appropriate deliberate defect still fails the affected check. Do not broadly suppress console warnings, accessibility rules, type errors, or screenshot differences to obtain a pass.
50
+
51
+ Repository instructions are guidance, not a security boundary. GitHub separately requires pull requests and the `verify` status check on `main`, and blocks force pushes/deletion. This solo-maintainer repository does not require an approving GitHub review or latest-push approval; its author can merge once checks pass and discussions are resolved. Independent agent review remains required for the changes described above. Keep verification/baseline changes visible in that review. Local tests cannot enforce GitHub branch settings.
52
+
53
+ The configured repository is [j4ckwinter/pancake-ui](https://github.com/j4ckwinter/pancake-ui). The main-branch policy is recorded in `.github/main-ruleset.json`: zero required approving reviews, no latest-push approval, resolved discussions, and the GitHub Actions `verify` check on an up-to-date branch. Force pushes and deletion are blocked, with no bypass actors. The [active GitHub ruleset](https://github.com/j4ckwinter/pancake-ui/rules/26247432) was read back on 2026-10-31 after the initial push. Check the [workflow runs](https://github.com/j4ckwinter/pancake-ui/actions/workflows/verify.yml) for current hosted results; a local green run does not establish hosted CI success.
54
+
55
+ After verification succeeds on a push to `main`, the workflow uploads the tested `.tmp/package` archive and its SHA-256/file manifest as `pancake-ui-package`. It does not rebuild or repack after testing. Pull-request runs and failed verification do not upload a consumer package. Artifacts are retained for 90 days. Consumers normally install the npm release and commit their lockfile; vendor the archive only when testing an unpublished change. Verify does not publish to npm. The separate manually dispatched Publish workflow validates and publishes that exact archive using npm trusted publishing; see [release setup](installation.md#publish-a-verified-release).
56
+
57
+ ## Dedicated component stories
58
+
59
+ Every public component has its own `src/stories/catalogue/<Component>.stories.tsx`. Use a named import from `src/index.ts`, explicit CSF metadata with the matching `component`, a title ending in the component name, and `tags: ["autodocs"]`. Export a `Default` story object and meaningful named variants, states or compositions. Include relevant disabled, error, loading, controlled and long-content examples. Keep args connected to rendering and provide working stateful interactions. Existing grouped catalogue and comparison stories remain useful alongside these entries.
60
+
61
+ `npm run check:stories` discovers public component exports using the same TypeScript symbol discovery as comparison coverage. It rejects missing or duplicate dedicated files, metadata for the wrong component, direct implementation imports, missing autodocs, and missing Default or additional examples. Metadata and story exports must use explicit objects; opaque spreads, accessors and computed keys are unsupported. Custom renderers must reference the component in JSX, directly or through local helper functions, so an unused import plus a placeholder renderer does not count. The check follows references rather than executing arbitrary JavaScript: it cannot prove every conditional path or judge whether every useful state is documented, so reviewers still assess the examples.
62
+
63
+ After a Storybook build, `npm run check:stories:built` requires every declared example and its autodocs page to appear in the generated index under the expected title and source path. This catches excluded stories and changes to Storybook discovery. The browser suite loads every dedicated example and docs page in Chromium, Firefox and WebKit, rejecting empty previews, error pages and unexpected runtime errors. These checks run in `verify`; focused component behavior contracts remain responsible for interaction correctness.
64
+
65
+ `npm run test:stories` proves the gate rejects representative missing and misleading coverage. Adding a public export without its dedicated story fails automatically; there is no hand-maintained component allowlist.
66
+
67
+ ## CI execution
68
+
69
+ GitHub runs Verify for pull requests and pushes to `main`, avoiding a second full run for each PR branch push. A newer revision cancels an older run of the same PR. Main-branch runs are not interrupted by newer pushes.
70
+
71
+ - `checks` runs `npm run check:source` for formatting, types, lint and source/guardrail checks.
72
+ - `build` runs `npm run verify:build` and `npm run prepare:tests` once. It builds Storybook, validates the package archive, and prepares the installed consumer and both React compatibility sites.
73
+ - Four `browsers` jobs download those exact outputs and run Chromium, Firefox, WebKit and visual projects independently. The Chromium job also runs `test:verification`, including deliberate browser-warning probes. All browser jobs keep the existing macOS runner, native-control locale, two-worker limit and screenshot expectations.
74
+ - The required `verify` job runs even when a dependency fails or is skipped. It only passes when `checks`, `build` and every browser matrix job succeeded. A successful main run then makes the tested package downloadable.
75
+
76
+ The internal build bundle is retained for two days and contains no `node_modules`; each job installs pinned tool dependencies itself. Consumer package downloads remain available for 90 days. `npm run verify` still runs the complete suite locally. `npm run test:ci` tests failure propagation and critical workflow wiring, including deliberate missing-browser and ignored-failure mutations.
77
+
78
+ The previous successful hosted run took 14.6 minutes, with 10.8 minutes in the browser suite. Parallel jobs are intended to reduce that critical path; a new hosted run is needed to measure the improvement. Queue time and available macOS concurrency can limit the gain.
79
+
80
+ `npm run test:archive` proves archive validation rejects missing code or font licenses and unexpected files. `npm run test:publish` exercises the source-run and publication archive gates, including deliberately invalid source and archive metadata. Both run in `check:source`.
package/package.json CHANGED
@@ -1,6 +1,109 @@
1
1
  {
2
2
  "name": "@jack.winter/pancake-ui",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "type": "module",
5
+ "description": "Reusable React components, compiled styles, and design tokens for web apps.",
6
+ "files": [
7
+ "dist",
8
+ "LICENSE",
9
+ "CHANGELOG.md",
10
+ "docs/styling.md",
11
+ "docs/verification.md",
12
+ "docs/installation.md",
13
+ "docs/components.md"
14
+ ],
15
+ "sideEffects": [
16
+ "**/*.css"
17
+ ],
18
+ "exports": {
19
+ ".": {
20
+ "types": "./dist/index.d.ts",
21
+ "import": "./dist/index.js"
22
+ },
23
+ "./styles.css": "./dist/styles.css",
24
+ "./theme.css": "./dist/theme.css",
25
+ "./fonts.css": "./dist/fonts.css"
26
+ },
27
+ "peerDependencies": {
28
+ "react": "^19.2.0",
29
+ "react-dom": "^19.2.0"
30
+ },
31
+ "engines": {
32
+ "node": ">=22.18.0"
33
+ },
34
+ "scripts": {
35
+ "tokens": "node scripts/generate-theme.mjs",
36
+ "build": "npm run tokens && vite build && tsc -p tsconfig.build.json && node scripts/copy-assets.mjs",
37
+ "typecheck": "tsc --noEmit",
38
+ "lint": "eslint .",
39
+ "format": "prettier --write .",
40
+ "format:check": "prettier --check .",
41
+ "storybook": "storybook dev -p 6006",
42
+ "storybook:build": "storybook build",
43
+ "example": "npm run build && npm --prefix examples/web install && npm --prefix examples/web run dev",
44
+ "test:package": "npm run prepare:tests && playwright test",
45
+ "verify": "npm run check:source && npm run test:verification && npm run verify:build && npm run test:package",
46
+ "prepack": "npm run build",
47
+ "release:local": "node scripts/release-local.mjs",
48
+ "check:styles": "node scripts/generate-theme.mjs --check && node scripts/check-styles.mjs",
49
+ "test:styles": "node --test scripts/style-*.test.mjs",
50
+ "check:comparison": "node scripts/check-comparison.mjs",
51
+ "test:comparison": "node --test scripts/check-comparison.test.mjs",
52
+ "test:visual": "npm run check:comparison && playwright test -c playwright.visual.config.ts",
53
+ "test:visual:update": "npm run check:comparison && npm run storybook:build && playwright test -c playwright.visual.config.ts --update-snapshots",
54
+ "check:contracts": "node scripts/check-contracts.mjs",
55
+ "test:contracts": "node --test scripts/check-contracts.test.mjs",
56
+ "test:verification": "node --test scripts/verification.test.mjs",
57
+ "check:compatibility": "node scripts/check-compatibility.mjs",
58
+ "check:structure": "node scripts/check-structure.mjs",
59
+ "test:structure": "node --test scripts/check-structure.test.mjs",
60
+ "check:stories": "node scripts/check-stories.mjs",
61
+ "test:stories": "node --test scripts/check-stories.test.mjs",
62
+ "check:stories:built": "node scripts/check-stories.mjs --built",
63
+ "check:source": "npm run format:check && npm run typecheck && npm run lint && npm run check:structure && npm run test:structure && npm run check:styles && npm run test:styles && npm run check:comparison && npm run test:comparison && npm run check:stories && npm run test:stories && npm run check:contracts && npm run test:contracts && npm run test:ci && npm run test:publish && npm run test:archive",
64
+ "verify:build": "npm run build && npm run storybook:build && npm run check:stories:built",
65
+ "prepare:tests": "node scripts/prepare-consumer.mjs && npm run check:compatibility",
66
+ "test:ci": "node --test scripts/ci.test.mjs",
67
+ "test:publish": "node --test scripts/publish.test.mjs",
68
+ "test:archive": "node --test scripts/validate-archive.test.mjs"
69
+ },
70
+ "devDependencies": {
71
+ "@axe-core/playwright": "4.14.0",
72
+ "@eslint/js": "10.0.1",
73
+ "@playwright/test": "1.64.1",
74
+ "@storybook/addon-a11y": "10.6.5",
75
+ "@storybook/addon-docs": "10.6.5",
76
+ "@storybook/react-vite": "10.6.5",
77
+ "@tailwindcss/vite": "4.3.3",
78
+ "@types/node": "26.6.6",
79
+ "@types/react": "19.3.0",
80
+ "@types/react-dom": "19.3.0",
81
+ "@vitejs/plugin-react": "6.1.2",
82
+ "eslint": "10.14.0",
83
+ "eslint-plugin-react-hooks": "7.1.1",
84
+ "globals": "17.13.0",
85
+ "postcss": "8.5.32",
86
+ "prettier": "3.9.10",
87
+ "react": "19.3.1",
88
+ "react-dom": "19.3.1",
89
+ "storybook": "10.6.5",
90
+ "tailwindcss": "4.3.3",
91
+ "typescript": "6.0.3",
92
+ "typescript-eslint": "8.72.1",
93
+ "vite": "8.3.5",
94
+ "yaml": "2.9.1"
95
+ },
96
+ "repository": {
97
+ "type": "git",
98
+ "url": "git+https://github.com/j4ckwinter/pancake-ui.git"
99
+ },
100
+ "homepage": "https://github.com/j4ckwinter/pancake-ui#readme",
101
+ "bugs": {
102
+ "url": "https://github.com/j4ckwinter/pancake-ui/issues"
103
+ },
104
+ "license": "MIT",
105
+ "publishConfig": {
106
+ "access": "public",
107
+ "registry": "https://registry.npmjs.org/"
108
+ }
109
+ }