@diagonal-hq/pages 0.1.0 → 0.1.2

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.
package/README.md CHANGED
@@ -1,32 +1,60 @@
1
1
  # `@diagonal-hq/pages`
2
2
 
3
- This package is the Page SDK for file-based workspaces. The pages of a workspace import its components, hooks, and providers. The package does not export them yet. It has no exports until the Page SDK moves into it.
3
+ This package is the Page SDK for file-based workspaces. The pages, layouts, and components of a workspace import its components, hooks, helpers, and other members by name:
4
4
 
5
- The package is ESM JavaScript with declarations. Its `exports` map has the package root and `package.json` only. A deep import into `dist/` fails.
5
+ ```tsx
6
+ import { Card, Image, page, useRecords, utils, type PageHandle } from '@diagonal-hq/pages';
7
+ ```
8
+
9
+ A page reads its route parameters and bound records from its props, `{ params, bindings }`, which `definePage` from `@diagonal-hq/cli` types. The `getRouteParam` and `getRouteBinding` helpers still work.
10
+
11
+ ## Exports
12
+
13
+ Each component, hook, and helper of the Page SDK, and each other top-level `Sdk` member except `Custom`, is one named export with the member's own name. `Sdk.Components.Image` is `Image`, `Sdk.hooks.useRecords` is `useRecords`, `Sdk.helpers.getInput` is `getInput`, and `Sdk.page` is `page`. The package does not export `Pages`. A file that names a page imports `Pages` from `@app/generated/pages` and passes the page uid to `utils`, such as `utils.page.url(Pages.Members_$Id.uid, { id })`. The deprecated top-level calendar hooks export once, as their hooks. Each type of the `Sdk` namespace is a type export with the same name. The package also exports the empty interfaces `ResourceCatalog`, `ResourceRecordCatalog`, and `PageParamsCatalog`. The `generated/catalog.d.ts` that `diagonal check` writes fills them with the resources and pages of the workspace. The internal namespace of the declarations, `SdkInternal`, is not an export.
14
+
15
+ The package has no default export and no `Sdk` export. A page imports a workspace component from its file, such as `import ClassCard from '../components/ClassCard'`.
16
+
17
+ The `Image` and `Map` components have the names of browser globals. In a file that also uses the global, import the component under another name:
18
+
19
+ ```tsx
20
+ import { Map as SdkMap } from '@diagonal-hq/pages';
21
+ ```
22
+
23
+ The generated export table `app/pages/resources/js/pageRuntime/sdk/generated/sdkExports.ts` owns the names. `npm run generate-page-sdk-types` writes it from the Page SDK contract, and it fails when two members have one export name. The page host, the package build, the Diagonal page build, the type check, and the `page-sdk-named-imports` codemod read it.
24
+
25
+ ## The page host binds the imports
26
+
27
+ The Diagonal page build binds each import of this package to the page host, `app/pages/resources/js/pageRuntime/modules/pageHost.ts`. The host gives each export a getter that reads the member of the Page SDK that renders the page. No SDK code is bundled into a workspace. A named import reads its member when the page renders. A module that reads one when it loads gets the error "The Page SDK is not ready".
28
+
29
+ The package JavaScript never runs inside a page. Outside a Diagonal page, importing it throws: "@diagonal-hq/pages runs only inside a Diagonal page. The Diagonal page build binds its imports to the page host."
30
+
31
+ The package is ESM JavaScript with declarations. Its `exports` map has the package root and `package.json` only. A deep import into `dist/` fails. `dist/index.d.ts` is one module. It declares no global and no ambient module, so a workspace that loads the `@diagonal-hq/cli` globals keeps one global `Sdk`. The declarations have their own copy of the React types that the SDK names, so they type-check with `@types/react` and without it.
6
32
 
7
33
  ## Dependencies
8
34
 
9
35
  React, React DOM, and `@inertiajs/react` are peer dependencies. The workspace installs them, so the application has one React instance and one Inertia instance.
10
36
 
11
- The package must not depend on `@diagonal-hq/workflow` or `@diagonal-hq/cli`. It must not import them, or their old module names `@diagonal/workflow` and `@diagonal/runtime`, from a source file. `npm run lint:package-boundaries` (`scripts/check-package-boundaries.mjs`) checks the manifest and the sources. CI runs it.
37
+ The package must not depend on `@diagonal-hq/workflows` or `@diagonal-hq/cli`. It must not import them, or the old workflow module name `@diagonal/workflow`, from a source file. `npm run lint:package-boundaries` (`scripts/check-package-boundaries.mjs`) checks the manifest and the sources. CI runs it. The export table is input of the package build, not an import of the package.
12
38
 
13
39
  ## Build the package
14
40
 
15
- `npm run build:pages-package` (`scripts/build-pages-package.mjs`) compiles `src/` with `tsconfig.json` into `dist/` and packs `scripts/dist/npm/diagonal-hq-pages-<version>.tgz`. A type error fails the build. `npm run generate-typescript` runs the script.
16
-
17
- `tsconfig.json` uses `NodeNext` module resolution. A relative import in `src/` must use the `.js` extension of the compiled file, so Node and a bundler can both load `dist/`.
41
+ `npm run build:pages-package` (`scripts/build-pages-package.mjs`) writes `dist/index.d.ts` and `dist/index.js` from the generated Page SDK contract and the export table, and packs `scripts/dist/npm/diagonal-hq-pages-<version>.tgz`. TypeScript checks the declarations, and a type error fails the build. `npm run generate-typescript` runs the script after `generate-page-sdk-types`.
18
42
 
19
- `node scripts/smoke-pages-package.mjs [tarball]` installs the packed tarball in a consumer outside the repository, with the React, React DOM, and Inertia versions of the platform. It checks the packed file list, the peer dependencies, the package boundaries of the packed manifest and of the installed dependency tree, the package root through the `exports` map, and a `tsc` check against the packed declarations. The `generated-assets` job of PR CI runs it.
43
+ `node scripts/smoke-pages-package.mjs [tarball]` installs the packed tarball in a consumer outside the repository, with the React, React DOM, and Inertia versions of the platform. It checks the packed file list, the peer dependencies, the package boundaries of the packed manifest and of the installed dependency tree, the error that the package root throws, the `exports` map, and a `tsc` check of a `.tsx` file that imports and renders named exports with `@types/react`. The `tsc` check also loads a `generated/catalog.d.ts` and checks that `SdkInternal` is not an export. `node scripts/check-runtime-templates.mjs` runs `diagonal check` and `tsc` on each workspace template with the packed packages. The `generated-assets` job of PR CI runs both.
20
44
 
21
45
  ## Publish the package
22
46
 
23
- The `Publish npm package` workflow (`.github/workflows/publish-npm-package.yml`) publishes the package to npm. It runs only from `main`.
47
+ The `Publish npm package` workflow (`.github/workflows/publish-npm-package.yml`) publishes the package to npm after each push to `main`. You can also run it from the Actions tab.
48
+
49
+ 1. The build job builds and packs the package. It compares the packed files with the tarball that npm has for the version in `package.json`. The `version` field does not count.
50
+ 2. When the files differ, a model reads the diff and the commit subjects since that publish. It classifies the change as breaking, feature, or fix. Before 1.0.0, a breaking change raises the minor part, and other changes raise the patch part. From 1.0.0, the workflow follows semantic versioning.
51
+ 3. The build job packs the package again at the new version and runs the smoke test on the tarball.
52
+ 4. The commit job commits the new version to `main` with an `[automated] release:` commit.
53
+ 5. The publish job runs in the `npm-publish` environment and publishes the tested bytes with npm trusted publishing. It does not build again. It refuses a version that npm already has.
24
54
 
25
- 1. Set `version` in `package.json` to a version that npm does not have. A version with a prerelease part, such as `0.2.0-next.1`, gets the `next` tag. Other versions get `latest`.
26
- 2. Merge the change to `main`.
27
- 3. Run the workflow from the Actions tab and select `pages`.
55
+ To choose a version yourself, such as 1.0.0 or a prerelease, set `version` in `package.json` to a version that npm does not have, and merge the change. The workflow publishes that version as it is. A version with a prerelease part, such as `0.2.0-next.1`, gets the `next` tag. Other versions get `latest`. The workflow does not raise a prerelease version. Set the next version by hand.
28
56
 
29
- The build job builds the package, packs it, and runs the smoke test on the tarball. The publish job runs in the `npm-publish` environment and publishes those exact bytes with npm trusted publishing. It refuses a version that npm already has.
57
+ The model call uses the `OPENROUTER_API_KEY` secret. When the call fails, the release fails. The workflow does not guess a version.
30
58
 
31
59
  npm must list `Diagonal-HQ/diagonal`, the `publish-npm-package.yml` workflow, and the `npm-publish` environment as the trusted publisher of `@diagonal-hq/pages`.
32
60