@akinon/pz-theme 2.0.146-rc.0 → 2.0.147-beta.0

package/CHANGELOG.md

@@ -1,40 +1,26 @@
 # @akinon/pz-theme
 
-## 2.0.146-rc.0
-
-### Patch Changes
-
-- Updated dependencies [86187b1c2]
-- Updated dependencies [0cf9ea239]
-- Updated dependencies [324f97d55]
-- Updated dependencies [51ea06888]
-- Updated dependencies
-- Updated dependencies [2fea41430]
-- Updated dependencies [b55acb768]
-- Updated dependencies [760258c1c]
-- Updated dependencies [143be2b9d]
-- Updated dependencies [7889b08fe]
-- Updated dependencies [9f8cd3bc5]
-- Updated dependencies [bfafa3f49]
-- Updated dependencies [57d7eb305]
-- Updated dependencies [d99a6a7d5]
-- Updated dependencies [9db81a714]
-- Updated dependencies [591e345e1]
-- Updated dependencies [4de5303c5]
-- Updated dependencies [95b139dc1]
-- Updated dependencies [1d00f2d06]
-- Updated dependencies [4ac7b2a1e]
-- Updated dependencies [e9598c71d]
-- Updated dependencies [4998a9631]
-- Updated dependencies [804d2bd6c]
-- Updated dependencies [3909d3224]
-- Updated dependencies [6a3d8a631]
-- Updated dependencies [e18836b20]
-- Updated dependencies [b1111d7b1]
-- Updated dependencies [1595d458e]
-- Updated dependencies [dca128112]
-  - @akinon/next@2.0.146-rc.0
-  - @akinon/theme-contract@2.0.146-rc.0
+## 2.0.147-beta.0
+
+### Patch Changes
+
+- Updated dependencies [cbbbfd757]
+  - @akinon/next@2.0.147-beta.0
+  - @akinon/theme-contract@2.0.147-beta.0
+
+## 2.0.146
+
+### Patch Changes
+
+- 7db9912: ZERO-5209: Document pz-theme on the v1 line and guard the composable-auth codemod
+
+  - The `@akinon/pz-theme` readme states the v1 compatibility policy: one release line from main, the versions that build on `@akinon/next` 1.x (2.0.106 and later), the core versions some editor features need, the setup a v1 brand needs, and the rules that keep the package buildable on v1. The `@akinon/theme-contract` readme points v1 storefronts there.
+  - `projectzero codemod --codemod=composable-auth` leaves a project without `@akinon/pz-theme`, or with one older than 2.0.41, untouched instead of writing a login layout whose import cannot resolve.
+  - `projectzero --plugins` offers List Hover Image (`pz-list-hover-image`), which its readme already told brands to install from there.
+
+- Updated dependencies [7db9912]
+  - @akinon/theme-contract@2.0.146
+  - @akinon/next@2.0.146
 
 ## 2.0.145
 

package/package.json

@@ -1,19 +1,19 @@
 {
   "name": "@akinon/pz-theme",
   "description": "Theme package for Project Zero Next — ThemePlaceholder system and theme editor infrastructure",
-  "version": "2.0.146-rc.0",
+  "version": "2.0.147-beta.0",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.146-rc.0",
+    "@akinon/next": "2.0.147-beta.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.146-rc.0",
+    "@akinon/theme-contract": "2.0.147-beta.0",
     "clsx": "2.1.1",
     "lottie-web": "^5.13.0",
     "react-multi-carousel": "2.8.4",
@@ -21,7 +21,7 @@
     "zod": "4.4.1"
   },
   "devDependencies": {
-    "@akinon/next": "2.0.146-rc.0",
+    "@akinon/next": "2.0.147-beta.0",
     "@testing-library/jest-dom": "5.16.4",
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.1.1",

package/readme.md

@@ -25,3 +25,124 @@ export default async function Page() {
 ### Custom sections and blocks
 
 Developer-authored sections and blocks are written against `@akinon/pz-theme/src/custom` — see [`src/custom/README.md`](./src/custom/README.md) and [`src/custom/README-sections.md`](./src/custom/README-sections.md). Reference examples live in `examples/header/` at the root of the pz-next repository; they are not shipped in the npm package.
+
+## Using pz-theme on the v1 line
+
+`@akinon/pz-theme` and `@akinon/theme-contract` have a single release line. They are developed on `main` and published with the 2.x packages; the `v1` branch has no copy of them and publishes no 1.x version. A brand still on v1 (Next 14.2, React 18, `@akinon/next` 1.x) installs the same releases as a v2 brand.
+
+### Which version
+
+| `@akinon/pz-theme` | On `@akinon/next` 1.x |
+| --- | --- |
+| 2.0.106 and later | Builds. Take the latest. |
+| 2.0.98 – 2.0.105 | Does not build on any v1 brand: `theme-fonts-link` writes a `precedence` prop that React 18's types do not declare (ZERO-5078). |
+| 2.0.94 – 2.0.97 | Builds only on 1.121.0 and later: the reset password block imports a query older cores do not export. |
+| 2.0.93 and earlier | Builds on 1.105.0 and later, without any of the later fixes. Older cores lack the `Modal` prop the image gallery passes. |
+
+Pin an exact version, as for every `@akinon` package. `@akinon/theme-contract` is a dependency of pz-theme and arrives with it at the same version, so it does not go in the brand's `package.json`.
+
+2.0.106 was checked on `@akinon/next` 1.91.0 (ZERO-5078). 2.0.143 was checked in a v1 brand on `@akinon/next` 1.126.16, Next 14.2.25 and `@types/react` 18: every source file of both packages type-checks and the brand builds.
+
+Two theme editor features also need a minimum core:
+
+| Feature | `@akinon/next` 1.x |
+| --- | --- |
+| `withPzConfig` transpiles pz-theme and theme-contract, and `pz-postinstall` keeps pz-theme installed | 1.126.17 (ZERO-5209). Older cores: step 3 below. |
+| Named previews ("View on site", the mobile QR code) | 1.126.15 (ZERO-5149), and only on the `[pz]` route segment |
+
+### Setting up a v1 brand
+
+1. Run `yarn add @akinon/pz-theme@<version> --exact`. Yarn then warns that pz-theme `has incorrect peer dependency "@akinon/next@<version>"`. The peer names the 2.x core the release was published with, so on v1 the warning is expected. npm 7 and later refuse the install instead, so install with Yarn.
+2. Let Tailwind see pz-theme. Its sections and blocks are styled with Tailwind classes that the brand's build generates, so add its sources to `content` in `tailwind.config.js`, as the 2.x app template does:
+
+   ```js
+   module.exports = {
+     content: [
+       // ...the brand's own globs
+       './node_modules/@akinon/pz-theme/src/**/*.{js,ts,jsx,tsx}'
+     ]
+   };
+   ```
+
+   A `'pz-theme'` entry in `src/plugins.js` has the same effect, because `getAkinonNextContent(plugins)` adds a glob for every entry.
+
+3. On a core older than 1.126.17, do two more things:
+
+   - Add `'pz-theme'` to `src/plugins.js`. Otherwise `pz-postinstall` removes the package on the next install.
+   - Append both packages to `transpilePackages` after `withPzConfig`. Declared inside `nextConfig`, the array would replace the core's list instead of extending it.
+
+     ```js
+     const config = withPzConfig(nextConfig);
+
+     export default {
+       ...config,
+       transpilePackages: [
+         ...(config.transpilePackages ?? []),
+         '@akinon/pz-theme',
+         '@akinon/theme-contract'
+       ]
+     };
+     ```
+
+   On 1.126.17 and later the `transpilePackages` override can go. Keep the `src/plugins.js` entry unless step 2's glob is in `tailwind.config.js`.
+
+4. Let the editor frame the storefront. The 1.x core's `Content-Security-Policy` allows `frame-ancestors` only for `'self'` and the akifast and akinoncloud origins. The 2.x core also allows Omnitron (`https://*.akinon.net`) and the local editor (`http://localhost:5174`). Add the same origins by rewriting the directive in the header `withPzConfig` emits; do not add a second header. Browsers enforce every CSP header, so a second one can only narrow the policy.
+
+   ```js
+   const EDITOR_ANCESTORS =
+     'https://*.akinon.net *.akinon.net http://localhost:5174 localhost:5174';
+
+   const withEditorFraming = (config) => ({
+     ...config,
+     headers: async () =>
+       ((await config.headers?.()) ?? []).map((group) => ({
+         ...group,
+         headers: (group.headers ?? []).map((header) =>
+           header.key.toLowerCase() === 'content-security-policy'
+             ? {
+                 ...header,
+                 value: header.value.replace(
+                   /frame-ancestors[^;]*/,
+                   (directive) => `${directive} ${EDITOR_ANCESTORS}`
+                 )
+               }
+             : header
+         )
+       }))
+   });
+   ```
+
+5. Set `NEXT_PUBLIC_THEME_EDITOR_ORIGINS` for production builds, as on v2 (see `@akinon/theme-contract`). The 1.x core does not serve `/theme-editor/health`, so the editor cannot name a missing variable. It treats the storefront as unknown and carries on, and without the variable the storefront ignores every edit.
+6. Mount the slots as a v2 brand does. For the login screen run `npx @akinon/projectzero@v1-latest --codemod=composable-auth`. It leaves a project without pz-theme untouched.
+
+### Keeping it buildable on v1
+
+Nothing in CI builds a v1 brand, so this compatibility holds only while every change to pz-theme keeps to these rules:
+
+- Never import, by name, a core export that only the 2.x core has. Read it off the module object and fall back when it is missing, as `load-placeholder-sections.ts` (`getWidgetSchemaData`, `getCollectionWidgetData`), `chrome/preview-snapshot-source.ts` (`getPreviewSnapshot`) and `blocks/reset-password-token-check.ts` do.
+- Never write a JSX prop that only React 19's types declare. Spread it from a `Record`, as `chrome/theme-fonts-link.tsx` does for `precedence`.
+- Code for the React 18 and RTK 1.9.7 runtime too. React 18 escapes `<style>` text children, so server-rendered CSS goes through `dangerouslySetInnerHTML` (`utils/css-safety.ts`). RTK 1.9.7 cannot seed its cache before the first render (`chrome/menu-seed-source.ts`).
+- Announce new storefront behaviour to the editor by name (`action-capabilities.ts`). Do not assume every storefront runs the latest pz-theme: a v1 brand stays on the release it pinned.
+
+Before releasing a change that touches core imports or JSX types, type-check the whole package in a v1 brand with the change installed. A tsconfig like this one, next to the brand's own, covers every source file, not only the ones the brand imports:
+
+```json
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": { "incremental": false },
+  "include": [
+    "*.d.ts",
+    "src/**/*.d.ts",
+    "node_modules/@akinon/pz-theme/src/**/*.ts",
+    "node_modules/@akinon/pz-theme/src/**/*.tsx",
+    "node_modules/@akinon/theme-contract/src/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules/**/__tests__/**",
+    "node_modules/**/*.test.ts",
+    "node_modules/**/*.test.tsx"
+  ]
+}
+```
+
+`npx tsc --noEmit -p <that file>` must report no error under `node_modules/@akinon`.