@elaraai/e3-cloud-ui 0.0.0-stage → 1.0.90

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 (63) hide show
  1. package/LICENSE.md +54 -0
  2. package/README.md +256 -2
  3. package/dist/src/authoring/app.d.ts +84 -0
  4. package/dist/src/authoring/app.d.ts.map +1 -0
  5. package/dist/src/authoring/app.js +38 -0
  6. package/dist/src/authoring/app.js.map +1 -0
  7. package/dist/src/authoring/link.d.ts +206 -0
  8. package/dist/src/authoring/link.d.ts.map +1 -0
  9. package/dist/src/authoring/link.js +114 -0
  10. package/dist/src/authoring/link.js.map +1 -0
  11. package/dist/src/authoring/page.d.ts +115 -0
  12. package/dist/src/authoring/page.d.ts.map +1 -0
  13. package/dist/src/authoring/page.js +113 -0
  14. package/dist/src/authoring/page.js.map +1 -0
  15. package/dist/src/browser.d.ts +19 -0
  16. package/dist/src/browser.d.ts.map +1 -0
  17. package/dist/src/browser.js +19 -0
  18. package/dist/src/browser.js.map +1 -0
  19. package/dist/src/build.d.ts +67 -0
  20. package/dist/src/build.d.ts.map +1 -0
  21. package/dist/src/build.js +228 -0
  22. package/dist/src/build.js.map +1 -0
  23. package/dist/src/check/check.d.ts +46 -0
  24. package/dist/src/check/check.d.ts.map +1 -0
  25. package/dist/src/check/check.js +342 -0
  26. package/dist/src/check/check.js.map +1 -0
  27. package/dist/src/check/index.d.ts +19 -0
  28. package/dist/src/check/index.d.ts.map +1 -0
  29. package/dist/src/check/index.js +19 -0
  30. package/dist/src/check/index.js.map +1 -0
  31. package/dist/src/check/package-view.d.ts +85 -0
  32. package/dist/src/check/package-view.d.ts.map +1 -0
  33. package/dist/src/check/package-view.js +87 -0
  34. package/dist/src/check/package-view.js.map +1 -0
  35. package/dist/src/check/scan.d.ts +99 -0
  36. package/dist/src/check/scan.d.ts.map +1 -0
  37. package/dist/src/check/scan.js +223 -0
  38. package/dist/src/check/scan.js.map +1 -0
  39. package/dist/src/check/types-equal.d.ts +31 -0
  40. package/dist/src/check/types-equal.d.ts.map +1 -0
  41. package/dist/src/check/types-equal.js +35 -0
  42. package/dist/src/check/types-equal.js.map +1 -0
  43. package/dist/src/index.d.ts +28 -0
  44. package/dist/src/index.d.ts.map +1 -0
  45. package/dist/src/index.js +28 -0
  46. package/dist/src/index.js.map +1 -0
  47. package/dist/src/runtime.d.ts +7 -0
  48. package/dist/src/runtime.d.ts.map +1 -0
  49. package/dist/src/runtime.js +7 -0
  50. package/dist/src/runtime.js.map +1 -0
  51. package/dist/src/types.d.ts +7169 -0
  52. package/dist/src/types.d.ts.map +1 -0
  53. package/dist/src/types.js +156 -0
  54. package/dist/src/types.js.map +1 -0
  55. package/dist/test/acme.examples.d.ts +99 -0
  56. package/dist/test/acme.examples.d.ts.map +1 -0
  57. package/dist/test/acme.examples.js +100 -0
  58. package/dist/test/acme.examples.js.map +1 -0
  59. package/dist/test/pages.examples.d.ts +33 -0
  60. package/dist/test/pages.examples.d.ts.map +1 -0
  61. package/dist/test/pages.examples.js +127 -0
  62. package/dist/test/pages.examples.js.map +1 -0
  63. package/package.json +71 -3
package/LICENSE.md ADDED
@@ -0,0 +1,54 @@
1
+ # Business Source License 1.1
2
+
3
+ Copyright (c) 2025 Elara AI Pty Ltd
4
+
5
+ ## License
6
+
7
+ **Licensor:** Elara AI Pty Ltd
8
+
9
+ **Licensed Work:** @elaraai/e3-cloud-ui
10
+
11
+ **Change Date:** Four years from the date of each release
12
+
13
+ **Change License:** AGPL-3.0
14
+
15
+ ## Terms
16
+
17
+ The Licensed Work is provided under the terms of the Business Source License 1.1 as detailed below.
18
+
19
+ ### Grant of Rights
20
+
21
+ The Licensor grants you the right to copy, modify, create derivative works, redistribute, and make non-production use of the Licensed Work.
22
+
23
+ ### Production Use Limitation
24
+
25
+ **"Production Use"** means any use by or on behalf of a for-profit entity, other than for evaluation, testing, or development purposes.
26
+
27
+ Production Use requires a separate commercial license from the Licensor.
28
+
29
+ ### Change Date
30
+
31
+ On the Change Date (four years after each release), the Licensed Work will be made available under the Change License (AGPL-3.0).
32
+
33
+ ### No Warranty
34
+
35
+ THE LICENSED WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. THE LICENSOR DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
36
+
37
+ ### Package-Specific Licenses
38
+
39
+ Individual packages within this repository may have different licensing terms. See the LICENSE.md file in each package directory for details.
40
+
41
+ ## Commercial Licensing
42
+
43
+ To obtain a commercial license for Production Use, contact:
44
+
45
+ **Email:** support@elara.ai
46
+ **Website:** https://elaraai.com
47
+
48
+ ## Governing Law
49
+
50
+ This license is governed by the laws of New South Wales, Australia.
51
+
52
+ ---
53
+
54
+ *Elara AI Pty Ltd*
package/README.md CHANGED
@@ -1,3 +1,257 @@
1
- # Temporary Holding Version
1
+ # @elaraai/e3-cloud-ui
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Apps for e3 cloud: a solution's pages and menu, deployed to a workspace apart
4
+ from its package, and drawn natively by the e3-cloud web app.
5
+
6
+ - Each app is its own section of the sidebar, its menu's pages its items.
7
+ - Each page has a URL, so deep links, Back and reload work.
8
+ - A page's crumbs follow its parents.
9
+ - An app carries the package it was built against, and every deploy is checked
10
+ against the workspace's package, so nothing an app binds can break silently.
11
+
12
+ Everything here is East types and East values: an app is a value of `AppType`,
13
+ encoded with beast2, and a page's body is East IR. Its version is the @elaraai
14
+ lockstep it is built against: install the one of the same version as your
15
+ east and e3.
16
+
17
+ ## Install
18
+
19
+ ```bash
20
+ npm install @elaraai/e3-cloud-ui@<your e3's version>
21
+ ```
22
+
23
+ Its peers are the same lockstep's `@elaraai/east`, `@elaraai/east-ui`,
24
+ `@elaraai/e3` and `@elaraai/e3-ui`.
25
+
26
+ ## A package and its apps
27
+
28
+ The package is a package, as always:
29
+
30
+ ```ts
31
+ // src/package.ts
32
+ export const lines = e3.input('lines', ArrayType(LineKey), variant('value', []));
33
+ export const target = e3.input('target', FloatType, variant('value', 100.0));
34
+ export const forecast = e3.task('forecast', [sales, target], …);
35
+ export const adjust = e3.function('adjust', …);
36
+ export const orders = e3.record('orders', DictType(StringType, Order), new Map());
37
+ export const approve = e3.mutation.reduce('approve', orders, …);
38
+ export const byLine = e3.recordIndex('by_line', orders, { key: … });
39
+ export const board = ui('board', [forecast.output], boardBody);
40
+
41
+ export default e3.package('acme', '1.5.0', forecast, board, adjust, orders, approve, byLine, lines);
42
+ ```
43
+
44
+ An app imports the package's defs, and binds them as a `ui()` body does:
45
+
46
+ ```tsx
47
+ // src/apps/ops.tsx
48
+ import { East, NullType } from '@elaraai/east';
49
+ import { Button, HStack, Reactive, Slider, Stat, Table, Text, VStack, UIComponentType } from '@elaraai/east-ui';
50
+ import { Data, Func, Record } from '@elaraai/e3-ui';
51
+ import { App, Menu, Nav, Page, PageLink } from '@elaraai/e3-cloud-ui';
52
+ import acme, { lines, target, forecast, board, adjust, orders, approve, byLine, LineKey } from '../package.js';
53
+
54
+ export const overview = Page('overview', { title: 'Overview', icon: 'gauge-high' },
55
+ () => East.function([], UIComponentType, _$ => (
56
+ <Reactive>{$ => {
57
+ const f = $.let(Data.bind(forecast)); // a task's output: read only
58
+ const t = $.let(Data.bind(target)); // an input: read and written
59
+ const rows = $.let(f.read());
60
+ const open = $.const(East.function([Table.Types.RowClickEvent], NullType, ($, e) => {
61
+ const r = $.let(rows.get(e.rowIndex));
62
+ $(Nav.go(line, { site: r.site, line: r.line }));
63
+ }));
64
+ return (
65
+ <VStack gap="4" align="stretch">
66
+ <Stat label="Target" value={East.print(t.read())} />
67
+ <Slider value={t.read()} min={0} max={200} onChangeEnd={t.write} />
68
+ <Table data={rows} columns={['site', 'line', 'units']} onRowClick={open} />
69
+ </VStack>
70
+ );
71
+ }}</Reactive>
72
+ )));
73
+
74
+ export const linesPage = Page('lines', { title: 'Lines', icon: 'industry', parent: overview },
75
+ () => East.function([], UIComponentType, _$ => (
76
+ <Reactive>{$ => {
77
+ const ls = $.let(Data.bind(lines));
78
+ return (
79
+ <VStack gap="2" align="flex-start">
80
+ {ls.read().map(($, key) => (
81
+ <PageLink to={line} params={key}>{East.str`${key.site} · ${key.line}`}</PageLink>
82
+ ))}
83
+ </VStack>
84
+ );
85
+ }}</Reactive>
86
+ )));
87
+
88
+ export const line = Page('line', { title: 'Line', icon: 'gears', parent: linesPage },
89
+ () => East.function([LineKey], UIComponentType, (_$, key) => (
90
+ <Reactive>{$ => {
91
+ const run = $.let(Func.bind(adjust));
92
+ const o = $.let(Record.bind(orders, [approve]));
93
+ const mine = $.let(Data.bindPaged(orders, { index: byLine }));
94
+ const adjustLine = $.const(East.function([], NullType, $ => { $(run.call(key, 5.0)); }));
95
+ const back = $.const(East.function([], NullType, $ => { $(Nav.back()); }));
96
+ return (
97
+ <VStack gap="3" align="stretch">
98
+ <Text>{East.str`${key.site} · ${key.line}`}</Text>
99
+ <HStack gap="2">
100
+ <Button loading={run.pending()} onClick={adjustLine}>Adjust by 5%</Button>
101
+ <Button variant="ghost" onClick={back}>Back</Button>
102
+ <PageLink to={overview}>Overview</PageLink>
103
+ </HStack>
104
+ <Table data={mine} columns={['ik', 'key']} />
105
+ </VStack>
106
+ );
107
+ }}</Reactive>
108
+ )));
109
+
110
+ export const boardPage = Page.task('board', board, { title: 'Board', icon: 'table-columns' });
111
+
112
+ export default App('ops', {
113
+ package: acme,
114
+ title: 'Acme Operations',
115
+ logo: readFileSync(new URL('./acme.svg', import.meta.url)),
116
+ home: overview,
117
+ menu: [Menu.group('Analyse', [overview, linesPage]), Menu.group('Plan', [boardPage])],
118
+ pages: [overview, linesPage, line, boardPage],
119
+ });
120
+ ```
121
+
122
+ The whole example, with a second app on the same workspace, is
123
+ `@elaraai/e3-cloud-ui/examples/acme`.
124
+
125
+ ## Pages
126
+
127
+ `Page(name, meta, () => East.function(…))` defines a page.
128
+
129
+ - **Its body** is a `ui()` body: an East function returning `UIComponentType`,
130
+ which runs in the browser when the page opens. It may use e3-ui's binds:
131
+ `Data.bind`, `Data.bindPaged`, `Func.bind`, `Record.bind`, `State`, and the
132
+ rest; the web app scopes each to what the page itself binds, and gives a
133
+ decision bind (`Decision.bind`) its platform, as `UITaskPreview` does.
134
+ - **It is given as a thunk**, `() => East.function(…)`, built when the app
135
+ builds. East builds a function's body as the function is made, and pages
136
+ link both ways (down to a detail, back up), so a body made at once could
137
+ link only to pages defined above it.
138
+ - **Its params** are the function's one argument, where a `ui()` task has its
139
+ compute-time inputs: none, or one (a struct for several, or any East type,
140
+ recursive types included). TypeScript takes their type from the function;
141
+ you never write it.
142
+ - **`meta`**: `title` (the bar's title, the sidebar's label and the crumb),
143
+ `icon` (a Font Awesome solid icon's name), and `parent` (another page: the
144
+ crumbs, and which menu item the sidebar lights).
145
+ - **Its name** is its URL segment, unique in the app, under e3's name rules.
146
+
147
+ `Page.task(name, uiTask, meta)` shows a `ui()` task's output: a UI the dataflow
148
+ computes, the same for every viewer. It takes no params.
149
+
150
+ ## Moving between pages
151
+
152
+ - `<PageLink to={page} params={…}>text</PageLink>` is a link within the app,
153
+ drawn as east-ui's `Link` is (`variant`, `colorPalette`). `params` is
154
+ required exactly when the target takes params, typed to them.
155
+ - `Nav.go(page, params?)` opens a page from an event handler, and `Nav.back()`
156
+ goes back as the browser does. Bind a handler once with
157
+ `$.const(East.function(…))`.
158
+
159
+ The web app pushes each page's URL, with its params in the query (`?p=`, in
160
+ East's JSON encoding), so a link can be shared and a reload keeps the page;
161
+ params past 2 KB of URL ride the browser's history instead, so such a link
162
+ works in its tab but not shared. A link to a page the app no longer has, or
163
+ params that no longer decode, opens the app's home and says so.
164
+
165
+ ## Menus and the app
166
+
167
+ - `Menu.group(label?, pages)` is a captioned, or uncaptioned, group of sidebar
168
+ items. A menu page takes no params.
169
+ - `App(name, config)` is the app: `package` (the package it was built against),
170
+ `title`, `logo` (a PNG, JPEG, WebP or SVG of at most 64 KiB, drawn in the
171
+ kiosk's logo region), `home` (a page without params), `menu`, and `pages`
172
+ (every page). Its name is its URL segment, unique in its workspace.
173
+
174
+ ## Building and deploying
175
+
176
+ ```ts
177
+ import { buildApp, exportApp } from '@elaraai/e3-cloud-ui';
178
+ import ops from './src/apps/ops.js';
179
+
180
+ const bundle = await buildApp(ops); // { app, package }
181
+ await exportApp(ops, 'dist/ops.app'); // the bundle, beast2
182
+ ```
183
+
184
+ `buildApp`:
185
+ 1. builds each page's body and compiles it to IR;
186
+ 2. reads it as e3-ui does: its manifest (`deriveManifest`), and the bound
187
+ datasets it writes and the mutations and indexes it uses
188
+ (`deriveUiAccess`);
189
+ 3. embeds the package exactly as `e3.export` writes it, and stamps the e3
190
+ release that exported it (`builtWith`);
191
+ 4. checks the app against that package, refusing it with every problem
192
+ (`AppBuildError`), so a bundle that could deploy nowhere never leaves your
193
+ machine.
194
+
195
+ The CLI builds and deploys:
196
+
197
+ ```
198
+ e3-cloud app build src/apps/ops.tsx -o dist/ops.app
199
+ e3-cloud app deploy <repo-url> staging dist/ops.app --dry-run
200
+ e3-cloud app deploy <repo-url> staging --from-source src/apps/ops.tsx
201
+ ```
202
+
203
+ A deploy of a bundle whose package the workspace already runs is UI-only and
204
+ instant. Another package deploys with it, and the app goes live as that deploy
205
+ completes. Either is refused unless the app fits the workspace's package.
206
+
207
+ An app is developed in the cloud: deploy each change to a workspace of your
208
+ own (a staging, never the protected workspace it releases to) and open it in
209
+ the console there, against that workspace's data. `--dry-run` checks a build
210
+ against the workspace's package and changes nothing.
211
+
212
+ ## The checks
213
+
214
+ `@elaraai/e3-cloud-ui/check`'s `checkApp(app, pkg, platform)` is the one check
215
+ the build and the cloud's deploys, releases and copies run. Types
216
+ are compared exactly, recursive types by structure. It answers
217
+ `AppProblem` values (from `@elaraai/e3-cloud-types`), each rendered as one
218
+ line by `appProblemText`:
219
+
220
+ | Check | A problem when |
221
+ |---|---|
222
+ | The app itself | a page name repeats; `home` is missing or takes params; a menu page is missing or takes params; a parent is missing, or parents loop; a link's target is missing, or its params are not the target's; a name e3 refuses; an icon outside Font Awesome's solid set; a logo that isn't a PNG, JPEG, WebP or SVG of at most 64 KiB |
223
+ | Datasets read | the dataset isn't in the package, or has another type |
224
+ | Datasets written | the dataset isn't writable (task outputs and records are not) |
225
+ | Paged sources | missing, or of another type |
226
+ | Functions | missing, or of another signature |
227
+ | Records | missing; another state type; a mutation or index the app uses is missing or of other types |
228
+ | `Page.task` pages | the task is missing, or isn't a UI task |
229
+ | e3 version | the app was built with another e3 than the platform runs |
230
+
231
+ ## The East types
232
+
233
+ `@elaraai/e3-cloud-ui/types` imports only `@elaraai/east` and
234
+ `@elaraai/e3-types`:
235
+
236
+ - `AppType`: name, title, logo, home, menu, pages, the package it was built
237
+ against, and the e3 it was built with.
238
+ - `PageType`: name, title, icon, parent, body (`east: IR` or `task: String`),
239
+ its manifest (e3's `DataManifest`), the datasets it writes, and its record
240
+ uses. A page's params type is its IR's own: `pageParamsType(page)`.
241
+ - `MenuGroupType`, `PageIconType`, `RecordUseType`, `AppPackageType`.
242
+ - `AppBundleType`: the app and its package's zip.
243
+
244
+ ## Entries
245
+
246
+ | Entry | Holds |
247
+ |---|---|
248
+ | `@elaraai/e3-cloud-ui` | authoring and the build (Node) |
249
+ | `@elaraai/e3-cloud-ui/browser` | authoring, browser-safe: a host implements `PageLink` and `Nav` from here |
250
+ | `@elaraai/e3-cloud-ui/types` | the East types |
251
+ | `@elaraai/e3-cloud-ui/check` | the checks |
252
+ | `@elaraai/e3-cloud-ui/jsx-runtime` | east-ui's JSX runtime |
253
+
254
+ ## License
255
+
256
+ [BSL 1.1](./LICENSE.md). Production use needs a commercial license from Elara
257
+ AI Pty Ltd. Each release becomes AGPL-3.0 four years after it is released.
@@ -0,0 +1,84 @@
1
+ /**
2
+ * Copyright (c) 2025 Elara AI Pty Ltd
3
+ * Licensed under BSL 1.1. See LICENSE for details.
4
+ */
5
+ /**
6
+ * `App` and `Menu`: an app's pages, its menu and the package it was built
7
+ * against.
8
+ *
9
+ * @packageDocumentation
10
+ */
11
+ import type { PackageDef } from '@elaraai/e3/browser';
12
+ import type { PageDef, PlainPageDef } from './page.js';
13
+ /** A group of an app's menu: a caption, or none, and its pages in order. */
14
+ export interface MenuGroupDef {
15
+ readonly kind: 'menu-group';
16
+ readonly label: string | null;
17
+ readonly pages: readonly PlainPageDef[];
18
+ }
19
+ /**
20
+ * Defines a group of an app's menu.
21
+ *
22
+ * @param label - Its caption in the sidebar
23
+ * @param pages - Its pages, in order; a menu page takes no params
24
+ * @returns The group
25
+ */
26
+ declare function group(label: string, pages: readonly PlainPageDef[]): MenuGroupDef;
27
+ /**
28
+ * Defines a group of an app's menu with no caption.
29
+ *
30
+ * @param pages - Its pages, in order; a menu page takes no params
31
+ * @returns The group
32
+ */
33
+ declare function group(pages: readonly PlainPageDef[]): MenuGroupDef;
34
+ /**
35
+ * An app's menu: its sidebar items, in groups.
36
+ *
37
+ * @example
38
+ * ```ts
39
+ * menu: [Menu.group('Analyse', [overview, lines]), Menu.group('Plan', [board])]
40
+ * ```
41
+ */
42
+ export declare const Menu: {
43
+ readonly group: typeof group;
44
+ };
45
+ /** What an app holds. */
46
+ export interface AppConfig {
47
+ /** The package the app was built against, which its bundle carries */
48
+ package: PackageDef<any>;
49
+ /** Its sidebar section's caption, and the kiosk's title */
50
+ title: string;
51
+ /** Its logo, in the kiosk's logo region: a PNG, JPEG, WebP or SVG of at most 64 KiB */
52
+ logo?: Uint8Array;
53
+ /** The page it opens on, which takes no params */
54
+ home: PlainPageDef;
55
+ /** Its sidebar items, in groups */
56
+ menu: readonly MenuGroupDef[];
57
+ /** Every page, in declaration order: the home page, the menu's, and every page they link to */
58
+ pages: readonly PageDef<string, any>[];
59
+ }
60
+ /** An app, as `App` defines it: what `buildApp` builds into a bundle. */
61
+ export interface AppDef {
62
+ readonly kind: 'app';
63
+ readonly name: string;
64
+ readonly config: AppConfig;
65
+ }
66
+ /**
67
+ * Defines an app.
68
+ *
69
+ * @param name - Its URL segment, unique in the workspace it deploys to (e3's name rules)
70
+ * @param config - Its package, title, logo, home page, menu and pages
71
+ * @returns The app, which `buildApp` builds into a bundle
72
+ *
73
+ * @example
74
+ * ```ts
75
+ * export default App('ops', {
76
+ * package: acme, title: 'Acme Operations', home: overview,
77
+ * menu: [Menu.group('Analyse', [overview, lines])],
78
+ * pages: [overview, lines, line],
79
+ * });
80
+ * ```
81
+ */
82
+ export declare function App(name: string, config: AppConfig): AppDef;
83
+ export {};
84
+ //# sourceMappingURL=app.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../src/authoring/app.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEvD,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;CACzC;AAED;;;;;;GAMG;AACH,iBAAS,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,YAAY,CAAC;AAC5E;;;;;GAKG;AACH,iBAAS,KAAK,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,YAAY,CAAC;AAO7D;;;;;;;GAOG;AACH,eAAO,MAAM,IAAI;;CAAqB,CAAC;AAEvC,yBAAyB;AACzB,MAAM,WAAW,SAAS;IACxB,sEAAsE;IACtE,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC;IACzB,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;IACd,uFAAuF;IACvF,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,kDAAkD;IAClD,IAAI,EAAE,YAAY,CAAC;IACnB,mCAAmC;IACnC,IAAI,EAAE,SAAS,YAAY,EAAE,CAAC;IAC9B,+FAA+F;IAC/F,KAAK,EAAE,SAAS,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;CACxC;AAED,yEAAyE;AACzE,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,MAAM,CAE3D"}
@@ -0,0 +1,38 @@
1
+ /**
2
+ * Copyright (c) 2025 Elara AI Pty Ltd
3
+ * Licensed under BSL 1.1. See LICENSE for details.
4
+ */
5
+ function group(labelOrPages, pages) {
6
+ return typeof labelOrPages === 'string'
7
+ ? { kind: 'menu-group', label: labelOrPages, pages: pages ?? [] }
8
+ : { kind: 'menu-group', label: null, pages: labelOrPages };
9
+ }
10
+ /**
11
+ * An app's menu: its sidebar items, in groups.
12
+ *
13
+ * @example
14
+ * ```ts
15
+ * menu: [Menu.group('Analyse', [overview, lines]), Menu.group('Plan', [board])]
16
+ * ```
17
+ */
18
+ export const Menu = { group };
19
+ /**
20
+ * Defines an app.
21
+ *
22
+ * @param name - Its URL segment, unique in the workspace it deploys to (e3's name rules)
23
+ * @param config - Its package, title, logo, home page, menu and pages
24
+ * @returns The app, which `buildApp` builds into a bundle
25
+ *
26
+ * @example
27
+ * ```ts
28
+ * export default App('ops', {
29
+ * package: acme, title: 'Acme Operations', home: overview,
30
+ * menu: [Menu.group('Analyse', [overview, lines])],
31
+ * pages: [overview, lines, line],
32
+ * });
33
+ * ```
34
+ */
35
+ export function App(name, config) {
36
+ return { kind: 'app', name, config };
37
+ }
38
+ //# sourceMappingURL=app.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"app.js","sourceRoot":"","sources":["../../../src/authoring/app.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAkCH,SAAS,KAAK,CAAC,YAA8C,EAAE,KAA+B;IAC5F,OAAO,OAAO,YAAY,KAAK,QAAQ;QACrC,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,KAAK,IAAI,EAAE,EAAE;QACjE,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC;AAC/D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,EAAE,KAAK,EAAW,CAAC;AAyBvC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,GAAG,CAAC,IAAY,EAAE,MAAiB;IACjD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AACvC,CAAC"}
@@ -0,0 +1,206 @@
1
+ /**
2
+ * Copyright (c) 2025 Elara AI Pty Ltd
3
+ * Licensed under BSL 1.1. See LICENSE for details.
4
+ */
5
+ /**
6
+ * `PageLink` and `Nav`: moving between an app's pages.
7
+ *
8
+ * `<PageLink to={page} params={…}>text</PageLink>` is a link within the app,
9
+ * drawn as east-ui's `Link` is. It is an extension component whose payload is
10
+ * an East value: the target's name and its params as a beast2 value of the
11
+ * target's params type. `Nav.go(page, params)` and `Nav.back()` are platform
12
+ * functions for event handlers. The web app implements all three: a link and
13
+ * `Nav.go` push the page's URL, and `Nav.back` is the browser's Back.
14
+ * TypeScript holds a link's params to its target's type.
15
+ *
16
+ * @packageDocumentation
17
+ */
18
+ import { BlobType, NullType, OptionType, StringType, StructType, type EastType, type ExprType, type SubtypeExprOrValue } from '@elaraai/east';
19
+ import { UIComponentType } from '@elaraai/east-ui';
20
+ import { type PageDef } from './page.js';
21
+ /**
22
+ * A page link's payload: the target page, its params as a beast2 value of the
23
+ * target's params type, the link's text and east-ui `Link`'s style.
24
+ */
25
+ export declare const PageLinkType: StructType<{
26
+ readonly to: StringType;
27
+ readonly params: OptionType<BlobType>;
28
+ readonly value: StringType;
29
+ readonly style: OptionType<StructType<{
30
+ readonly variant: import("@elaraai/east").OptionType<import("@elaraai/east").VariantType<{
31
+ readonly underline: import("@elaraai/east").NullType;
32
+ readonly plain: import("@elaraai/east").NullType;
33
+ }>>;
34
+ readonly colorPalette: import("@elaraai/east").OptionType<StringType>;
35
+ readonly color: import("@elaraai/east").OptionType<StringType>;
36
+ readonly hoverColor: import("@elaraai/east").OptionType<StringType>;
37
+ readonly visitedColor: import("@elaraai/east").OptionType<StringType>;
38
+ readonly textDecoration: import("@elaraai/east").OptionType<import("@elaraai/east").VariantType<{
39
+ readonly none: import("@elaraai/east").NullType;
40
+ readonly underline: import("@elaraai/east").NullType;
41
+ readonly "line-through": import("@elaraai/east").NullType;
42
+ readonly overline: import("@elaraai/east").NullType;
43
+ }>>;
44
+ readonly lineHeight: import("@elaraai/east").OptionType<StringType>;
45
+ readonly letterSpacing: import("@elaraai/east").OptionType<StringType>;
46
+ readonly overflow: import("@elaraai/east").OptionType<import("@elaraai/east").VariantType<{
47
+ readonly visible: import("@elaraai/east").NullType;
48
+ readonly hidden: import("@elaraai/east").NullType;
49
+ readonly scroll: import("@elaraai/east").NullType;
50
+ readonly auto: import("@elaraai/east").NullType;
51
+ }>>;
52
+ readonly overflowX: import("@elaraai/east").OptionType<import("@elaraai/east").VariantType<{
53
+ readonly visible: import("@elaraai/east").NullType;
54
+ readonly hidden: import("@elaraai/east").NullType;
55
+ readonly scroll: import("@elaraai/east").NullType;
56
+ readonly auto: import("@elaraai/east").NullType;
57
+ }>>;
58
+ readonly overflowY: import("@elaraai/east").OptionType<import("@elaraai/east").VariantType<{
59
+ readonly visible: import("@elaraai/east").NullType;
60
+ readonly hidden: import("@elaraai/east").NullType;
61
+ readonly scroll: import("@elaraai/east").NullType;
62
+ readonly auto: import("@elaraai/east").NullType;
63
+ }>>;
64
+ readonly width: import("@elaraai/east").OptionType<StringType>;
65
+ readonly height: import("@elaraai/east").OptionType<StringType>;
66
+ readonly minWidth: import("@elaraai/east").OptionType<StringType>;
67
+ readonly minHeight: import("@elaraai/east").OptionType<StringType>;
68
+ readonly maxWidth: import("@elaraai/east").OptionType<StringType>;
69
+ readonly maxHeight: import("@elaraai/east").OptionType<StringType>;
70
+ readonly padding: import("@elaraai/east").OptionType<import("@elaraai/east").StructType<{
71
+ readonly top: import("@elaraai/east").OptionType<StringType>;
72
+ readonly right: import("@elaraai/east").OptionType<StringType>;
73
+ readonly bottom: import("@elaraai/east").OptionType<StringType>;
74
+ readonly left: import("@elaraai/east").OptionType<StringType>;
75
+ }>>;
76
+ readonly margin: import("@elaraai/east").OptionType<import("@elaraai/east").StructType<{
77
+ readonly top: import("@elaraai/east").OptionType<StringType>;
78
+ readonly right: import("@elaraai/east").OptionType<StringType>;
79
+ readonly bottom: import("@elaraai/east").OptionType<StringType>;
80
+ readonly left: import("@elaraai/east").OptionType<StringType>;
81
+ }>>;
82
+ readonly opacity: import("@elaraai/east").OptionType<import("@elaraai/east").FloatType>;
83
+ }>>;
84
+ }>;
85
+ export type PageLinkType = typeof PageLinkType;
86
+ /** The page link component, which a host implements (`implementUIComponent`). */
87
+ export declare const PageLinkComponent: import("@elaraai/east-ui").UIComponentDef<StructType<{
88
+ readonly to: StringType;
89
+ readonly params: OptionType<BlobType>;
90
+ readonly value: StringType;
91
+ readonly style: OptionType<StructType<{
92
+ readonly variant: import("@elaraai/east").OptionType<import("@elaraai/east").VariantType<{
93
+ readonly underline: import("@elaraai/east").NullType;
94
+ readonly plain: import("@elaraai/east").NullType;
95
+ }>>;
96
+ readonly colorPalette: import("@elaraai/east").OptionType<StringType>;
97
+ readonly color: import("@elaraai/east").OptionType<StringType>;
98
+ readonly hoverColor: import("@elaraai/east").OptionType<StringType>;
99
+ readonly visitedColor: import("@elaraai/east").OptionType<StringType>;
100
+ readonly textDecoration: import("@elaraai/east").OptionType<import("@elaraai/east").VariantType<{
101
+ readonly none: import("@elaraai/east").NullType;
102
+ readonly underline: import("@elaraai/east").NullType;
103
+ readonly "line-through": import("@elaraai/east").NullType;
104
+ readonly overline: import("@elaraai/east").NullType;
105
+ }>>;
106
+ readonly lineHeight: import("@elaraai/east").OptionType<StringType>;
107
+ readonly letterSpacing: import("@elaraai/east").OptionType<StringType>;
108
+ readonly overflow: import("@elaraai/east").OptionType<import("@elaraai/east").VariantType<{
109
+ readonly visible: import("@elaraai/east").NullType;
110
+ readonly hidden: import("@elaraai/east").NullType;
111
+ readonly scroll: import("@elaraai/east").NullType;
112
+ readonly auto: import("@elaraai/east").NullType;
113
+ }>>;
114
+ readonly overflowX: import("@elaraai/east").OptionType<import("@elaraai/east").VariantType<{
115
+ readonly visible: import("@elaraai/east").NullType;
116
+ readonly hidden: import("@elaraai/east").NullType;
117
+ readonly scroll: import("@elaraai/east").NullType;
118
+ readonly auto: import("@elaraai/east").NullType;
119
+ }>>;
120
+ readonly overflowY: import("@elaraai/east").OptionType<import("@elaraai/east").VariantType<{
121
+ readonly visible: import("@elaraai/east").NullType;
122
+ readonly hidden: import("@elaraai/east").NullType;
123
+ readonly scroll: import("@elaraai/east").NullType;
124
+ readonly auto: import("@elaraai/east").NullType;
125
+ }>>;
126
+ readonly width: import("@elaraai/east").OptionType<StringType>;
127
+ readonly height: import("@elaraai/east").OptionType<StringType>;
128
+ readonly minWidth: import("@elaraai/east").OptionType<StringType>;
129
+ readonly minHeight: import("@elaraai/east").OptionType<StringType>;
130
+ readonly maxWidth: import("@elaraai/east").OptionType<StringType>;
131
+ readonly maxHeight: import("@elaraai/east").OptionType<StringType>;
132
+ readonly padding: import("@elaraai/east").OptionType<import("@elaraai/east").StructType<{
133
+ readonly top: import("@elaraai/east").OptionType<StringType>;
134
+ readonly right: import("@elaraai/east").OptionType<StringType>;
135
+ readonly bottom: import("@elaraai/east").OptionType<StringType>;
136
+ readonly left: import("@elaraai/east").OptionType<StringType>;
137
+ }>>;
138
+ readonly margin: import("@elaraai/east").OptionType<import("@elaraai/east").StructType<{
139
+ readonly top: import("@elaraai/east").OptionType<StringType>;
140
+ readonly right: import("@elaraai/east").OptionType<StringType>;
141
+ readonly bottom: import("@elaraai/east").OptionType<StringType>;
142
+ readonly left: import("@elaraai/east").OptionType<StringType>;
143
+ }>>;
144
+ readonly opacity: import("@elaraai/east").OptionType<import("@elaraai/east").FloatType>;
145
+ }>>;
146
+ }>>;
147
+ /** A page link's props: its target, the target's params when it takes any, its text and its style. */
148
+ export type PageLinkProps<P extends EastType | null> = {
149
+ /** The page it links to */
150
+ to: PageDef<string, P>;
151
+ /** The link's text */
152
+ children: SubtypeExprOrValue<StringType>;
153
+ /** east-ui `Link`'s variant: underlined always, or plain */
154
+ variant?: 'underline' | 'plain';
155
+ /** east-ui `Link`'s colour palette */
156
+ colorPalette?: string;
157
+ } & (P extends EastType ? {
158
+ params: SubtypeExprOrValue<P>;
159
+ } : {
160
+ params?: undefined;
161
+ });
162
+ /**
163
+ * A link to a page of the app, drawn as east-ui's `Link`.
164
+ *
165
+ * @param props - The target page, its params when it takes any, the text and the style
166
+ * @returns The link
167
+ *
168
+ * @example
169
+ * ```tsx
170
+ * {ls.read().map(($, key) => (
171
+ * <PageLink to={line} params={key}>{East.str`${key.site} · ${key.line}`}</PageLink>
172
+ * ))}
173
+ * ```
174
+ */
175
+ export declare function PageLink<P extends EastType | null>(props: PageLinkProps<P>): ExprType<UIComponentType>;
176
+ /**
177
+ * Moving between an app's pages from an event handler.
178
+ *
179
+ * @example
180
+ * ```tsx
181
+ * <Button onClick={East.function([], NullType, $ => { $(Nav.go(line, key)); })}>Open</Button>
182
+ * <Button onClick={East.function([], NullType, $ => { $(Nav.back()); })}>Back</Button>
183
+ * ```
184
+ */
185
+ export declare const Nav: {
186
+ /**
187
+ * Opens a page of the app, pushing its URL.
188
+ *
189
+ * @param page - The page
190
+ * @param params - Its params, when it takes any
191
+ * @returns Null
192
+ */
193
+ readonly go: <P extends EastType | null>(page: PageDef<string, P>, ...params: P extends EastType ? [SubtypeExprOrValue<P>] : []) => ExprType<NullType>;
194
+ /**
195
+ * Goes back to the page before, as the browser's Back does.
196
+ *
197
+ * @returns Null
198
+ */
199
+ readonly back: () => ExprType<NullType>;
200
+ /** The platform functions a host implements: `go` and `back`. */
201
+ readonly platform: {
202
+ readonly go: import("@elaraai/east").GenericPlatformDefinition<readonly ["P"], readonly [StringType, "P"], NullType>;
203
+ readonly back: import("@elaraai/east").PlatformDefinition<[], NullType>;
204
+ };
205
+ };
206
+ //# sourceMappingURL=link.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"link.d.ts","sourceRoot":"","sources":["../../../src/authoring/link.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,QAAQ,EAAQ,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAC5D,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,KAAK,kBAAkB,EACtD,MAAM,eAAe,CAAC;AACvB,OAAO,EAAgB,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEjE,OAAO,EAAmB,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AAK1D;;;GAGG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKvB,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC;AAE/C,iFAAiF;AACjF,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAAqE,CAAC;AAEpG,sGAAsG;AACtG,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,QAAQ,GAAG,IAAI,IAAI;IACrD,2BAA2B;IAC3B,EAAE,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACvB,sBAAsB;IACtB,QAAQ,EAAE,kBAAkB,CAAC,UAAU,CAAC,CAAC;IACzC,4DAA4D;IAC5D,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;IAChC,sCAAsC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,CAAC,CAAC,SAAS,QAAQ,GAAG;IAAE,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAA;CAAE,GAAG;IAAE,MAAM,CAAC,EAAE,SAAS,CAAA;CAAE,CAAC,CAAC;AAYtF;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,QAAQ,GAAG,IAAI,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,eAAe,CAAC,CActG;AAQD;;;;;;;;GAQG;AACH,eAAO,MAAM,GAAG;IACd;;;;;;OAMG;kBACA,CAAC,SAAS,QAAQ,GAAG,IAAI,QAAQ,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,aAAa,CAAC,SAAS,QAAQ,GAAG,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,KAAG,QAAQ,CAAC,QAAQ,CAAC;IAOzI;;;;OAIG;yBACK,QAAQ,CAAC,QAAQ,CAAC;IAG1B,iEAAiE;;;;;CAEzD,CAAC"}