@almateam/app-sdk 0.9.0 → 0.10.0
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 +90 -45
- package/app.d.ts +297 -0
- package/cli.js +307 -10
- package/files.d.ts +25 -0
- package/index.d.ts +49 -5
- package/index.js +570 -234
- package/navigation.d.ts +44 -2
- package/package.json +1 -1
- package/siteRuntime.d.ts +41 -14
- package/site.d.ts +0 -267
package/README.md
CHANGED
|
@@ -8,19 +8,18 @@ An app imports the SDK as `@alma/app-sdk`. Install the published package under
|
|
|
8
8
|
that name, for its types:
|
|
9
9
|
|
|
10
10
|
```sh
|
|
11
|
-
npm install --save-dev @alma/app-sdk@npm:@almateam/app-sdk@^0.
|
|
11
|
+
npm install --save-dev @alma/app-sdk@npm:@almateam/app-sdk@^0.10.0
|
|
12
12
|
```
|
|
13
13
|
|
|
14
14
|
Alma builds an app's source with its own current copy of the SDK, whatever
|
|
15
15
|
version the source installs or pins, so the copy you install never ships. The
|
|
16
16
|
SDK's runtime has no dependency and holds no credential (the `alma-app` command
|
|
17
|
-
uses the MCP client)
|
|
18
|
-
|
|
17
|
+
uses the MCP client). An app is one set of screens (see "Screens" below); in
|
|
18
|
+
Alma's isolated frame its SDK, `useAlma()` from `@alma/app-ui`, talks to the
|
|
19
|
+
host as the member viewing it:
|
|
19
20
|
|
|
20
21
|
```ts
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
const alma = createAppSdk(hostTransport());
|
|
22
|
+
const alma = useAlma();
|
|
24
23
|
const page = await alma.listTopics({
|
|
25
24
|
type: "account",
|
|
26
25
|
filter: ["stage:eq:Live"],
|
|
@@ -389,18 +388,20 @@ try {
|
|
|
389
388
|
}
|
|
390
389
|
```
|
|
391
390
|
|
|
392
|
-
##
|
|
391
|
+
## Screens: one app in Alma and on the web
|
|
393
392
|
|
|
394
|
-
An app
|
|
395
|
-
|
|
396
|
-
|
|
393
|
+
An app is one module, `src/app.tsx` (or the module the manifest names in
|
|
394
|
+
`screens: { entry }`), that default-exports `defineApp`. Members see its
|
|
395
|
+
routes in Alma's frame; published, anyone sees them at
|
|
396
|
+
`<name>.sites.alma.team`, with no sign-in and no Alma around them. It is the
|
|
397
|
+
same source in both places:
|
|
397
398
|
|
|
398
399
|
```tsx
|
|
399
|
-
import {
|
|
400
|
+
import { defineApp, defineRoute } from "@alma/app-sdk";
|
|
400
401
|
import { Frame } from "./Frame";
|
|
401
402
|
import { posts } from "./posts";
|
|
402
403
|
|
|
403
|
-
export default
|
|
404
|
+
export default defineApp({
|
|
404
405
|
meta: {
|
|
405
406
|
name: "Field Notes",
|
|
406
407
|
description: "Notes from the field.",
|
|
@@ -408,13 +409,14 @@ export default defineSite({
|
|
|
408
409
|
favicon: { light: "/_files/icon.png", dark: "/_files/icon-dark.png" },
|
|
409
410
|
},
|
|
410
411
|
layout: Frame,
|
|
411
|
-
|
|
412
|
+
routes: [
|
|
412
413
|
{
|
|
413
414
|
path: "/",
|
|
414
415
|
component: () => import("./pages/Home"),
|
|
415
416
|
meta: () => ({ title: "Home" }),
|
|
416
417
|
},
|
|
417
|
-
|
|
418
|
+
{ path: "/desk", audience: "members", component: () => import("./Desk") },
|
|
419
|
+
defineRoute({
|
|
418
420
|
path: "/notes/:slug",
|
|
419
421
|
addresses: () => posts.map((post) => ({ slug: post.slug })),
|
|
420
422
|
load: ({ slug }) => posts.find((post) => post.slug === slug)!,
|
|
@@ -428,35 +430,63 @@ export default defineSite({
|
|
|
428
430
|
});
|
|
429
431
|
```
|
|
430
432
|
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
433
|
+
A route is for members and the public both, unless its `audience` says
|
|
434
|
+
`members` (only in Alma: never built at the published address) or `public`
|
|
435
|
+
(only there). One path may be a members' screen and a public one. `meta`,
|
|
436
|
+
`themeScript`, `fonts`, `files` and `embeds` describe the published address;
|
|
437
|
+
an app that only members see needs none of them.
|
|
438
|
+
|
|
439
|
+
Published, Alma builds every address of every public route to its own HTML
|
|
440
|
+
document when it builds the version: a route with parameters (`:slug`) is
|
|
441
|
+
built at each address its `addresses` lists, and only there (in Alma, every
|
|
442
|
+
address that fits is the route's). `load` runs then, and again in the browser
|
|
443
|
+
when a person moves to the route, so it returns plain JSON. Each public route
|
|
435
444
|
gets its title, description, canonical address, Open Graph and X tags from its
|
|
436
|
-
`meta`, and the site gets `sitemap.xml`, `robots.txt` and
|
|
437
|
-
(`notFound`, or a plain one). An address names a
|
|
438
|
-
where a static segment and a parameter could both fit, the
|
|
439
|
-
redirect's `from` is one address or a prefix ending `/*`,
|
|
440
|
-
prefix itself and everything under it; an address a
|
|
441
|
-
the
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
445
|
+
`meta`, which it must have, and the site gets `sitemap.xml`, `robots.txt` and
|
|
446
|
+
a `404.html` (`notFound`, or a plain one). An address names a route without a
|
|
447
|
+
trailing slash; where a static segment and a parameter could both fit, the
|
|
448
|
+
static one wins. A redirect's `from` is one address or a prefix ending `/*`,
|
|
449
|
+
which moves the prefix itself and everything under it; an address a route
|
|
450
|
+
lists is served by the route. `throw notFound()` from `load` shows the
|
|
451
|
+
not-found screen.
|
|
452
|
+
|
|
453
|
+
Alma's build starts the app with `startApp` from the kit: at the published
|
|
454
|
+
address it takes up the page the build rendered, over the site's transport
|
|
455
|
+
and the browser's history; in Alma's frame it renders the route at the
|
|
456
|
+
host's address, over the host's transport and history. Either way it moves
|
|
457
|
+
between routes without loading a document.
|
|
447
458
|
|
|
448
459
|
```tsx
|
|
449
|
-
import {
|
|
460
|
+
import {
|
|
461
|
+
Link,
|
|
462
|
+
Markdown,
|
|
463
|
+
useAlma,
|
|
464
|
+
useApp,
|
|
465
|
+
useFileUrl,
|
|
466
|
+
usePath,
|
|
467
|
+
} from "@alma/app-ui";
|
|
450
468
|
```
|
|
451
469
|
|
|
452
|
-
`Link` moves within the
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
470
|
+
`Link` moves within the app; to anywhere else it is an ordinary link at the
|
|
471
|
+
published address, and in Alma the host opens it in a new tab when a person
|
|
472
|
+
clicks it (the frame never loads a document of its own). `usePath` and
|
|
473
|
+
`useApp` say where the person is, in which place (`frame` or `public`) and on
|
|
474
|
+
which origin, and `Markdown` draws a `.md` file's tokens. A capitalised tag in
|
|
475
|
+
the Markdown (`<Callout kind="note">`) is one of the app's components, passed
|
|
476
|
+
in `components`; a name it was not given, or any other HTML, fails the build.
|
|
457
477
|
|
|
458
|
-
|
|
459
|
-
|
|
478
|
+
Neither build adds anything of Alma's look to an app that does not ask, so a
|
|
479
|
+
member and a visitor see what the author wrote. To stand on Alma's (its
|
|
480
|
+
tokens, Geist, the accent and the kit's Theme knobs, beneath the app's own
|
|
481
|
+
CSS, and Alma's tokens on its Tailwind utilities), import it once, in both
|
|
482
|
+
places alike:
|
|
483
|
+
|
|
484
|
+
```ts
|
|
485
|
+
import "@alma/app-ui/base.css";
|
|
486
|
+
```
|
|
487
|
+
|
|
488
|
+
In Alma, `useAlma()` is the member's SDK. A visitor is nobody Alma knows, so
|
|
489
|
+
at the published address it can only raise the events the version declares;
|
|
460
490
|
`viewer()` and `shell()` answer null, and everything else rejects with
|
|
461
491
|
`site.no_viewer`. Where an event's workflow answers the visitor, the raise
|
|
462
492
|
returns a `result` ticket: `waitForResult(result.token)` reads the answer, and
|
|
@@ -476,10 +506,17 @@ try {
|
|
|
476
506
|
}
|
|
477
507
|
```
|
|
478
508
|
|
|
479
|
-
|
|
509
|
+
An app's pictures, fonts, PDFs and audio are files, not source. Put them in
|
|
480
510
|
one flat folder, `_site-files` in the app's folder by default (or name another
|
|
481
|
-
with `--files <folder>`), and
|
|
482
|
-
|
|
511
|
+
with `--files <folder>`), and show each with `useFileUrl("<name>")`, which is
|
|
512
|
+
`/_files/<name>` at the published address and, in Alma's frame (which reaches
|
|
513
|
+
no network), a blob: URL of the bytes the host hands over; Markdown's
|
|
514
|
+
`` does the same. In the frame an `<img>`, `<audio>`,
|
|
515
|
+
`<video>` or `<source>` written with `src="/_files/<name>"`, and a stylesheet's
|
|
516
|
+
`url(/_files/<name>)` (a font's `@font-face`, a background), are pointed at the
|
|
517
|
+
same bytes, so the screens look the same in both places; a `Link` to
|
|
518
|
+
`/_files/<name>`, or to a declared plain file, saves the file there.
|
|
519
|
+
`_site-files/cover.webp` is `useFileUrl("cover.webp")`. A name is letters, digits,
|
|
483
520
|
dots, dashes and underscores, and a folder inside the folder is refused. The
|
|
484
521
|
types are `png`, `jpg`, `jpeg`, `gif`, `webp`, `avif`, `ico`, `woff2`, `woff`,
|
|
485
522
|
`ttf`, `otf`, `pdf`, `mp3`, `m4a`, `aac`, `ogg`, `oga`, `opus`, `wav`, `weba`
|
|
@@ -499,21 +536,29 @@ machine), take its entry out and push again.
|
|
|
499
536
|
npx alma-app push ./app --files ./_site-files --org <organization id>
|
|
500
537
|
```
|
|
501
538
|
|
|
502
|
-
|
|
503
|
-
|
|
539
|
+
Publishing a version follows the workspace's approval level for sharing apps;
|
|
540
|
+
going public counts as widening who sees it.
|
|
504
541
|
|
|
505
542
|
## Developing an app
|
|
506
543
|
|
|
507
544
|
The package carries the `alma-app` command, which runs under Node.
|
|
508
545
|
`npx alma-app dev [folder] --app <app id>` (or `bunx`) pushes the folder's
|
|
509
|
-
source (`manifest.json` beside `
|
|
510
|
-
`.js`, `.mjs`, `.css`, `.html`, `.svg` and `.
|
|
511
|
-
`node_modules`, `dist`, `build`, dotfiles and lockfiles) as a
|
|
546
|
+
source (`manifest.json` beside `src/`, and the `.tsx`, `.ts`, `.jsx`,
|
|
547
|
+
`.js`, `.mjs`, `.css`, `.html`, `.svg`, `.json`, `.md` and `.txt` files around
|
|
548
|
+
it, leaving out `node_modules`, `dist`, `build`, dotfiles and lockfiles) as a
|
|
549
|
+
new draft version
|
|
512
550
|
now and on every save, signed in as you in the browser; Alma builds it and your
|
|
513
551
|
draft moves to it. `npx alma-app push` pushes once. Without `--app` the first
|
|
514
552
|
push starts a new app; a member of several workspaces names one with
|
|
515
553
|
`--org <organization id>`.
|
|
516
554
|
|
|
555
|
+
An app written as one page (`index.html` loading its own script) becomes an
|
|
556
|
+
app with screens with `npx alma-app convert [folder]`: the page's body and
|
|
557
|
+
scripts become the one members' route, on Alma's look as before, and the
|
|
558
|
+
manifest names `screens.entry`. An inline or outside script, or a head element
|
|
559
|
+
other than the title and the page's own stylesheets, is not carried over:
|
|
560
|
+
the command names each and changes nothing.
|
|
561
|
+
|
|
517
562
|
While you have your own app open, what it logs (`console`) and every error it
|
|
518
563
|
does not catch show in its Manage sheet, under Logs, beside how the workflows it
|
|
519
564
|
starts last ran. Only your own sessions are heard: what an app logs can carry
|
package/app.d.ts
ADDED
|
@@ -0,0 +1,297 @@
|
|
|
1
|
+
/** The literal every absolute URL is written with at build time. A build
|
|
2
|
+
* does not know where its app will be published; publishing replaces this
|
|
3
|
+
* in every text file with the address's own origin. */
|
|
4
|
+
export declare const SITE_ORIGIN_TOKEN = "__ALMA_SITE_ORIGIN__";
|
|
5
|
+
/** The id `assetsFor` and a route's hydration data name the not-found
|
|
6
|
+
* screen by. Every route is named by its `path`, which starts with `/`. */
|
|
7
|
+
export declare const NOT_FOUND_ROUTE_ID = "404";
|
|
8
|
+
/** Where an app is running: inside Alma's frame for a member, or at its
|
|
9
|
+
* published address for anyone. */
|
|
10
|
+
export type AppPlace = "frame" | "public";
|
|
11
|
+
/** Who a route is for: `members` in Alma's frame only, `public` at the
|
|
12
|
+
* published address only. A route that names neither is in both. */
|
|
13
|
+
export type RouteAudience = "members" | "public";
|
|
14
|
+
/** A route's parameters, by the names its `path` gives them (`:slug`). */
|
|
15
|
+
export type RouteParams = Record<string, string>;
|
|
16
|
+
export type JsonValue = string | number | boolean | null | JsonValue[] | {
|
|
17
|
+
[key: string]: JsonValue;
|
|
18
|
+
};
|
|
19
|
+
export type JsonLd = {
|
|
20
|
+
[key: string]: JsonValue;
|
|
21
|
+
};
|
|
22
|
+
/** A title and description shown where a page is shared, when they are not
|
|
23
|
+
* the page's own. */
|
|
24
|
+
export interface SharedText {
|
|
25
|
+
title?: string;
|
|
26
|
+
description?: string;
|
|
27
|
+
}
|
|
28
|
+
/** What one route says about itself in its published document's head. */
|
|
29
|
+
export interface RouteMeta {
|
|
30
|
+
title: string;
|
|
31
|
+
/** The title shown as it is, without the app's `titleTemplate`. */
|
|
32
|
+
absoluteTitle?: boolean;
|
|
33
|
+
description?: string;
|
|
34
|
+
/** The route's own address (a path), when it is not the address it was
|
|
35
|
+
* served at. */
|
|
36
|
+
canonical?: string;
|
|
37
|
+
/** A path on the published address (`/_files/cover.png`) or an absolute
|
|
38
|
+
* https URL. */
|
|
39
|
+
image?: string;
|
|
40
|
+
imageAlt?: string;
|
|
41
|
+
/** Open Graph `og:type`; `website` unless said. */
|
|
42
|
+
type?: "website" | "article";
|
|
43
|
+
/** What Open Graph shows, where it is not the route's title, description
|
|
44
|
+
* and image (or the app's `openGraph`). */
|
|
45
|
+
openGraph?: SharedText & {
|
|
46
|
+
image?: string;
|
|
47
|
+
};
|
|
48
|
+
/** What X shows, where it is not the route's title and description (or
|
|
49
|
+
* the app's `x`). */
|
|
50
|
+
x?: SharedText;
|
|
51
|
+
/** Kept out of search engines and the sitemap. */
|
|
52
|
+
noindex?: boolean;
|
|
53
|
+
jsonLd?: JsonLd | JsonLd[];
|
|
54
|
+
}
|
|
55
|
+
/** What the whole app says about itself at its published address, beneath
|
|
56
|
+
* every route's own meta. */
|
|
57
|
+
export interface AppMeta {
|
|
58
|
+
name: string;
|
|
59
|
+
description?: string;
|
|
60
|
+
/** The document's `lang`; `en` unless said. */
|
|
61
|
+
lang?: string;
|
|
62
|
+
/** Open Graph `og:locale`, such as `en_US`. */
|
|
63
|
+
locale?: string;
|
|
64
|
+
/** How a route's title is shown, with `%s` where it goes. Without one a
|
|
65
|
+
* route's title is used as it is. */
|
|
66
|
+
titleTemplate?: string;
|
|
67
|
+
/** The image a route without its own shares with, and its size in
|
|
68
|
+
* pixels. */
|
|
69
|
+
image?: string;
|
|
70
|
+
imageAlt?: string;
|
|
71
|
+
imageWidth?: number;
|
|
72
|
+
imageHeight?: number;
|
|
73
|
+
/** What Open Graph and X show for a route that gives none of its own:
|
|
74
|
+
* without these, the route's title and description. */
|
|
75
|
+
openGraph?: SharedText;
|
|
76
|
+
x?: SharedText;
|
|
77
|
+
/** The app's account on X, such as `@alma`. */
|
|
78
|
+
twitter?: string;
|
|
79
|
+
/** One icon, or one for each colour scheme. */
|
|
80
|
+
favicon?: string | {
|
|
81
|
+
light: string;
|
|
82
|
+
dark: string;
|
|
83
|
+
};
|
|
84
|
+
themeColor?: string | {
|
|
85
|
+
light: string;
|
|
86
|
+
dark: string;
|
|
87
|
+
};
|
|
88
|
+
/** Addresses search engines are asked not to crawl. */
|
|
89
|
+
robots?: {
|
|
90
|
+
disallow?: string[];
|
|
91
|
+
};
|
|
92
|
+
jsonLd?: JsonLd | JsonLd[];
|
|
93
|
+
}
|
|
94
|
+
/** What a route's component is rendered with. */
|
|
95
|
+
export interface RouteProps<D = unknown> {
|
|
96
|
+
params: RouteParams;
|
|
97
|
+
data: D;
|
|
98
|
+
path: string;
|
|
99
|
+
}
|
|
100
|
+
export type RouteComponent<D = unknown> = {
|
|
101
|
+
bivarianceHack(props: RouteProps<D>): unknown;
|
|
102
|
+
}["bivarianceHack"];
|
|
103
|
+
export type AppLayout = {
|
|
104
|
+
bivarianceHack(props: {
|
|
105
|
+
children: unknown;
|
|
106
|
+
path: string;
|
|
107
|
+
}): unknown;
|
|
108
|
+
}["bivarianceHack"];
|
|
109
|
+
export interface RouteMetaContext<D = unknown> {
|
|
110
|
+
params: RouteParams;
|
|
111
|
+
data: D;
|
|
112
|
+
/** The address being described. */
|
|
113
|
+
path: string;
|
|
114
|
+
app: AppMeta;
|
|
115
|
+
}
|
|
116
|
+
export interface SitemapOptions {
|
|
117
|
+
changeFrequency?: "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never";
|
|
118
|
+
/** From 0 to 1. */
|
|
119
|
+
priority?: number;
|
|
120
|
+
/** An ISO 8601 date. */
|
|
121
|
+
lastModified?: string;
|
|
122
|
+
}
|
|
123
|
+
export interface AppRoute<D = unknown> {
|
|
124
|
+
/** `/`, `/about`, or a pattern with parameters such as `/blog/:slug`. */
|
|
125
|
+
path: string;
|
|
126
|
+
/** Who the route is for; members and the public both unless said. A
|
|
127
|
+
* route is not routable where its audience is not: a `members` route
|
|
128
|
+
* is never built at the published address, and a `public` one is not
|
|
129
|
+
* in Alma's frame. */
|
|
130
|
+
audience?: RouteAudience;
|
|
131
|
+
/** The route's own module, split from every other route's at the
|
|
132
|
+
* published address. */
|
|
133
|
+
component(): Promise<{
|
|
134
|
+
default: RouteComponent<D>;
|
|
135
|
+
}>;
|
|
136
|
+
/** Every parameter set a pattern is published at. A public route with
|
|
137
|
+
* parameters must list them: an address no route lists is not built.
|
|
138
|
+
* In Alma's frame every address that fits the pattern is the route's. */
|
|
139
|
+
addresses?(): RouteParams[] | Promise<RouteParams[]>;
|
|
140
|
+
/** The route's data, read when its public address is built, and in the
|
|
141
|
+
* browser whenever a person moves to it. It must be plain JSON. */
|
|
142
|
+
load?(params: RouteParams): D | Promise<D>;
|
|
143
|
+
/** The route's document head at the published address, which a public
|
|
144
|
+
* route must have. */
|
|
145
|
+
meta?(context: RouteMetaContext<D>): RouteMeta;
|
|
146
|
+
/** Left out of the sitemap with `false`; listed by default. */
|
|
147
|
+
sitemap?: boolean | SitemapOptions;
|
|
148
|
+
}
|
|
149
|
+
/** The statuses a redirect may answer with: 301 and 308 for a permanent
|
|
150
|
+
* move, 302 and 307 for a temporary one. */
|
|
151
|
+
export declare const SITE_REDIRECT_STATUSES: readonly [301, 302, 307, 308];
|
|
152
|
+
/** A move. `from` is one address, or a prefix ending `/*` that moves the
|
|
153
|
+
* prefix itself and every address under it. `to` is one address of this
|
|
154
|
+
* app or an absolute https URL, used as it is. */
|
|
155
|
+
export interface SiteRedirect {
|
|
156
|
+
from: string;
|
|
157
|
+
to: string;
|
|
158
|
+
status: (typeof SITE_REDIRECT_STATUSES)[number];
|
|
159
|
+
}
|
|
160
|
+
export interface SiteFont {
|
|
161
|
+
/** A path on the published address, such as `/_files/inter.woff2`. */
|
|
162
|
+
href: string;
|
|
163
|
+
/** `font/woff2` unless said. */
|
|
164
|
+
type?: string;
|
|
165
|
+
}
|
|
166
|
+
/** A plain file the published address serves, by its path (`llms.txt`). */
|
|
167
|
+
export type SiteFile = string | ((context: {
|
|
168
|
+
origin: string;
|
|
169
|
+
app: AppMeta;
|
|
170
|
+
}) => string | Promise<string>);
|
|
171
|
+
/** One app's screens, which `src/app.tsx` default-exports. Members see the
|
|
172
|
+
* routes for them in Alma's frame; visitors see the public ones at the
|
|
173
|
+
* published address, each prerendered. `meta`, `themeScript`, `fonts`,
|
|
174
|
+
* `files` and `embeds` describe the published address alone. */
|
|
175
|
+
export interface AppDefinition {
|
|
176
|
+
routes: AppRoute[];
|
|
177
|
+
/** Wraps every route, the not-found screen included. */
|
|
178
|
+
layout?: AppLayout;
|
|
179
|
+
/** The screen shown at an address no route has. */
|
|
180
|
+
notFound?: {
|
|
181
|
+
component(): Promise<{
|
|
182
|
+
default: RouteComponent<null>;
|
|
183
|
+
}>;
|
|
184
|
+
meta?: RouteMeta;
|
|
185
|
+
};
|
|
186
|
+
redirects?: SiteRedirect[];
|
|
187
|
+
/** The published address's name and head; an app needs it to publish. */
|
|
188
|
+
meta?: AppMeta;
|
|
189
|
+
/** Run first in every published document's head, before anything
|
|
190
|
+
* paints, to set the colour scheme. Without one it is
|
|
191
|
+
* `DEFAULT_THEME_SCRIPT`. */
|
|
192
|
+
themeScript?: string;
|
|
193
|
+
/** Fonts every published document preloads. */
|
|
194
|
+
fonts?: SiteFont[];
|
|
195
|
+
files?: Record<string, SiteFile>;
|
|
196
|
+
/** Origins the published routes may frame, such as
|
|
197
|
+
* `https://calendar.google.com`. */
|
|
198
|
+
embeds?: string[];
|
|
199
|
+
}
|
|
200
|
+
/** Sets `<html data-theme>` from the visitor's saved choice
|
|
201
|
+
* (`localStorage["alma-site-theme"]`) or their system's scheme. */
|
|
202
|
+
export declare const DEFAULT_THEME_SCRIPT: string;
|
|
203
|
+
export declare function defineApp(app: AppDefinition): AppDefinition;
|
|
204
|
+
/** A route whose `load`, component and `meta` share one data type. */
|
|
205
|
+
export declare function defineRoute<D>(route: AppRoute<D>): AppRoute;
|
|
206
|
+
/** The app as it is in `place`: only the routes whose audience is there. */
|
|
207
|
+
export declare function appIn(app: AppDefinition, place: AppPlace): AppDefinition;
|
|
208
|
+
/** Thrown from a route's `load`: this address has no route. */
|
|
209
|
+
export declare function notFound(): Error;
|
|
210
|
+
export declare function isNotFound(error: unknown): boolean;
|
|
211
|
+
/** Why `address` is not a clean address (`/` or `/a/b`: no trailing slash,
|
|
212
|
+
* no empty, dot or `index.html` segment, no query or fragment), or null. */
|
|
213
|
+
export declare function siteAddressProblem(address: string): string | null;
|
|
214
|
+
/** The parameters `address` gives `pattern`, or null where it does not fit. */
|
|
215
|
+
export declare function matchPattern(pattern: string, address: string): RouteParams | null;
|
|
216
|
+
/** The address a pattern makes with `params`, each value encoded. */
|
|
217
|
+
export declare function fillPattern(pattern: string, params: RouteParams): string;
|
|
218
|
+
/** The redirect that moves `address`, as the edge applies them: one whose
|
|
219
|
+
* `from` is the address itself first, then the longest `/*` prefix that
|
|
220
|
+
* is the address or one of its parents. */
|
|
221
|
+
export declare function matchRedirect(redirects: readonly SiteRedirect[], address: string): SiteRedirect | null;
|
|
222
|
+
export type AddressMatch<R extends {
|
|
223
|
+
path: string;
|
|
224
|
+
} = AppRoute> = {
|
|
225
|
+
kind: "route";
|
|
226
|
+
route: R;
|
|
227
|
+
params: RouteParams;
|
|
228
|
+
} | {
|
|
229
|
+
kind: "redirect";
|
|
230
|
+
redirect: SiteRedirect;
|
|
231
|
+
};
|
|
232
|
+
/** What an app shows at `address` among the routes it is given (one
|
|
233
|
+
* place's, from `appIn`): a route and its parameters, a redirect, or null
|
|
234
|
+
* for its not-found screen. A route whose path is the address, and a
|
|
235
|
+
* redirect from exactly the address, are one key at the edge and so come
|
|
236
|
+
* first (an app may not have both); then a route whose pattern fits, a
|
|
237
|
+
* static segment winning over a parameter; then a `/*` redirect.
|
|
238
|
+
*
|
|
239
|
+
* The edge holds only the addresses the build listed. Given them as
|
|
240
|
+
* `listed`, a route with parameters fits only an address it listed, and
|
|
241
|
+
* any other falls through to the redirects, so the answer is the edge's
|
|
242
|
+
* own. Without them, every address that fits a pattern is that route's. */
|
|
243
|
+
export declare function matchAddress<R extends {
|
|
244
|
+
path: string;
|
|
245
|
+
}>(app: {
|
|
246
|
+
routes: readonly R[];
|
|
247
|
+
redirects?: readonly SiteRedirect[];
|
|
248
|
+
}, address: string, listed?: ReadonlySet<string>): AddressMatch<R> | null;
|
|
249
|
+
export interface ListedAddress {
|
|
250
|
+
route: AppRoute;
|
|
251
|
+
params: RouteParams;
|
|
252
|
+
address: string;
|
|
253
|
+
}
|
|
254
|
+
/** Every address the given routes list (one place's, from `appIn`), in
|
|
255
|
+
* their order: a route without parameters at its path, one with them at
|
|
256
|
+
* each parameter set its `addresses` gives. Throws when an address is not
|
|
257
|
+
* clean, is listed twice, or would be served by another route or a
|
|
258
|
+
* redirect. */
|
|
259
|
+
export declare function listAddresses(app: Pick<AppDefinition, "routes" | "redirects">): Promise<ListedAddress[]>;
|
|
260
|
+
/** The content type a declared plain file is served with, or null for an
|
|
261
|
+
* extension the published address cannot declare. */
|
|
262
|
+
export declare function siteFileContentType(path: string): string | null;
|
|
263
|
+
/** Everything wrong with an app's definition that can be told without
|
|
264
|
+
* running it, each as a sentence, for the places named (both unless
|
|
265
|
+
* said). Empty when there is nothing. */
|
|
266
|
+
export declare function appDefinitionProblems(app: AppDefinition, places?: readonly AppPlace[]): string[];
|
|
267
|
+
/** Whether `address` is one of the app's declared plain files rather than
|
|
268
|
+
* a route: `/llms.txt` for `llms.txt`, `/manifesto` for
|
|
269
|
+
* `manifesto/index.html`. The edge serves it as its own document, so
|
|
270
|
+
* moving there is a page load. */
|
|
271
|
+
export declare function isSiteFileAddress(app: Pick<AppDefinition, "files">, address: string): boolean;
|
|
272
|
+
/** Where a route's address is written in the published output. */
|
|
273
|
+
export declare function outputPathOf(address: string): string;
|
|
274
|
+
/** `path` made absolute on `origin`; an absolute URL is kept as it is. */
|
|
275
|
+
export declare function absoluteUrl(origin: string, path: string): string;
|
|
276
|
+
export declare function escapeHtml(text: string): string;
|
|
277
|
+
/** JSON safe inside a `<script>` data block: nothing in it can close the
|
|
278
|
+
* element or end a line in a script. */
|
|
279
|
+
export declare function scriptJson(value: unknown): string;
|
|
280
|
+
/** A route's title as the published address shows it. */
|
|
281
|
+
export declare function pageTitle(app: AppMeta, meta: RouteMeta): string;
|
|
282
|
+
/** The tags a published document's head carries for what its route says
|
|
283
|
+
* about itself: title, description, canonical, Open Graph, X, JSON-LD,
|
|
284
|
+
* icons, theme colour and font preloads. Every URL in them is absolute on
|
|
285
|
+
* `origin`. */
|
|
286
|
+
export declare function buildDocumentHead(input: {
|
|
287
|
+
app: AppMeta;
|
|
288
|
+
meta: RouteMeta;
|
|
289
|
+
address: string;
|
|
290
|
+
origin: string;
|
|
291
|
+
fonts?: readonly SiteFont[];
|
|
292
|
+
}): string;
|
|
293
|
+
export interface SitemapEntry extends SitemapOptions {
|
|
294
|
+
address: string;
|
|
295
|
+
}
|
|
296
|
+
export declare function buildSitemap(origin: string, entries: readonly SitemapEntry[]): string;
|
|
297
|
+
export declare function buildRobots(origin: string, robots?: AppMeta["robots"]): string;
|