@diagonal-hq/pages 0.1.1 → 0.1.3
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 +31 -7
- package/dist/index.d.ts +15238 -0
- package/dist/index.js +229 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,22 +1,46 @@
|
|
|
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
|
|
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
|
-
|
|
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/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.
|
|
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`)
|
|
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
|
|
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
|
|