singularity-core 0.17.0 → 0.17.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 +1 -1
- package/dist/telemetry/index.d.ts +1 -0
- package/dist/telemetry/index.js +1 -0
- package/dist/telemetry/sentry.d.ts +122 -0
- package/dist/telemetry/sentry.js +178 -0
- package/dist/theme/index.d.ts +11 -0
- package/dist/theme/index.js +15 -0
- package/dist/theme/react.d.ts +27 -2
- package/dist/theme/react.js +27 -4
- package/dist/theme/server.d.ts +12 -0
- package/dist/theme/server.js +24 -6
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -15,4 +15,4 @@ export const { login, logout, getValidSession, hasUserPermission } =
|
|
|
15
15
|
createCookieSession({ client: fetchAuthServerClient, cookiePrefix: "filion" });
|
|
16
16
|
```
|
|
17
17
|
|
|
18
|
-
See [AGENTS.md](./AGENTS.md) for the subpaths and the rules for adding code. Open fixes are in [IMPROVEMENTS.md](./IMPROVEMENTS.md).
|
|
18
|
+
See [AGENTS.md](./AGENTS.md) for the subpaths and the rules for adding code. Open fixes are in [IMPROVEMENTS.md](./IMPROVEMENTS.md). What each version contains is in [RELEASE_NOTES.md](./RELEASE_NOTES.md).
|
package/dist/telemetry/index.js
CHANGED
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Sentry error reporting, shared by an app's browser and server setup. No
|
|
3
|
+
* Sentry import: the app passes `sentryOptions` to its own SDK's `init`, so
|
|
4
|
+
* this package needs no Sentry dependency. The types below are the parts of
|
|
5
|
+
* Sentry's events, spans and breadcrumbs the scrubbers touch.
|
|
6
|
+
*
|
|
7
|
+
* Reports carry no cookies, tokens, request bodies, query strings or the
|
|
8
|
+
* visitor's IP address. The SDK is told not to collect them
|
|
9
|
+
* (`dataCollection`), and the scrubbers remove them again before anything
|
|
10
|
+
* is sent, in case an integration adds them anyway.
|
|
11
|
+
*/
|
|
12
|
+
/** The part of a Sentry event's `request` the scrubber touches. */
|
|
13
|
+
export type SentryEventRequest = {
|
|
14
|
+
url?: string;
|
|
15
|
+
headers?: Record<string, string>;
|
|
16
|
+
cookies?: unknown;
|
|
17
|
+
data?: unknown;
|
|
18
|
+
query_string?: unknown;
|
|
19
|
+
env?: unknown;
|
|
20
|
+
};
|
|
21
|
+
/** The part of a Sentry breadcrumb the scrubber touches. */
|
|
22
|
+
export type SentryBreadcrumb = {
|
|
23
|
+
category?: string;
|
|
24
|
+
data?: Record<string, unknown>;
|
|
25
|
+
};
|
|
26
|
+
/** The part of a Sentry stack frame the scrubber touches. */
|
|
27
|
+
export type SentryStackFrame = {
|
|
28
|
+
filename?: string;
|
|
29
|
+
abs_path?: string;
|
|
30
|
+
};
|
|
31
|
+
/** The part of a Sentry error event the scrubber touches. */
|
|
32
|
+
export type SentryEvent = {
|
|
33
|
+
request?: SentryEventRequest;
|
|
34
|
+
user?: {
|
|
35
|
+
ip_address?: string | null;
|
|
36
|
+
};
|
|
37
|
+
breadcrumbs?: SentryBreadcrumb[];
|
|
38
|
+
exception?: {
|
|
39
|
+
values?: {
|
|
40
|
+
stacktrace?: {
|
|
41
|
+
frames?: SentryStackFrame[];
|
|
42
|
+
};
|
|
43
|
+
}[];
|
|
44
|
+
};
|
|
45
|
+
};
|
|
46
|
+
/** The part of a Sentry span the scrubber touches. */
|
|
47
|
+
export type SentrySpan = {
|
|
48
|
+
attributes?: Record<string, unknown>;
|
|
49
|
+
};
|
|
50
|
+
/** What the SDK may collect on its own. Everything personal is off. */
|
|
51
|
+
export type SentryDataCollection = {
|
|
52
|
+
userInfo: false;
|
|
53
|
+
cookies: false;
|
|
54
|
+
httpHeaders: {
|
|
55
|
+
allow: string[];
|
|
56
|
+
};
|
|
57
|
+
httpBodies: never[];
|
|
58
|
+
urlQueryParams: false;
|
|
59
|
+
stackFrameVariables: false;
|
|
60
|
+
};
|
|
61
|
+
/**
|
|
62
|
+
* Options for `Sentry.init`, the same on the browser and the server. The app
|
|
63
|
+
* adds what is its own: the browser's `tunnel` and integrations.
|
|
64
|
+
*/
|
|
65
|
+
export type SentrySharedOptions = {
|
|
66
|
+
dsn: string;
|
|
67
|
+
environment: string | undefined;
|
|
68
|
+
release: string | undefined;
|
|
69
|
+
/** 10% of requests and page loads as traces, as in the webapi. */
|
|
70
|
+
tracesSampleRate: number;
|
|
71
|
+
dataCollection: SentryDataCollection;
|
|
72
|
+
beforeSend: <T extends SentryEvent>(event: T) => T;
|
|
73
|
+
beforeSendSpan: <T extends SentrySpan>(span: T) => T;
|
|
74
|
+
beforeBreadcrumb: <T extends SentryBreadcrumb>(breadcrumb: T) => T | null;
|
|
75
|
+
/** Drops every log: the apps send errors and traces only. */
|
|
76
|
+
beforeSendLog: () => null;
|
|
77
|
+
};
|
|
78
|
+
/**
|
|
79
|
+
* True for a DSN Sentry can use: an absolute http(s) URL. An unset value, an
|
|
80
|
+
* empty one and an undefined Azure variable (written literally as
|
|
81
|
+
* `$(NAME)`) all turn reporting off, as in the webapi.
|
|
82
|
+
*/
|
|
83
|
+
export declare function isSentryDsn(value: string | undefined): value is string;
|
|
84
|
+
/**
|
|
85
|
+
* Removes what a report must not carry from an error event: cookies, the
|
|
86
|
+
* request body, query strings, environment, headers other than the user
|
|
87
|
+
* agent, the visitor's IP and console breadcrumbs. A stack frame in one of
|
|
88
|
+
* the page's inline scripts is named after the page's URL, so frames lose
|
|
89
|
+
* their query string too. Changes the event in place and returns it, as
|
|
90
|
+
* `beforeSend` expects.
|
|
91
|
+
*/
|
|
92
|
+
export declare function scrubSentryEvent<T extends SentryEvent>(event: T): T;
|
|
93
|
+
/**
|
|
94
|
+
* Drops console breadcrumbs, since a console line can hold anything (the
|
|
95
|
+
* apps' request log has the visitor's IP), and takes the query string off
|
|
96
|
+
* the URLs of the rest. For `beforeBreadcrumb`.
|
|
97
|
+
*/
|
|
98
|
+
export declare function scrubSentryBreadcrumb<T extends SentryBreadcrumb>(breadcrumb: T): T | null;
|
|
99
|
+
/**
|
|
100
|
+
* Removes the visitor's address, query strings and headers other than the
|
|
101
|
+
* user agent from a span's attributes, and the query string from its URLs.
|
|
102
|
+
* For `beforeSendSpan`.
|
|
103
|
+
*/
|
|
104
|
+
export declare function scrubSentrySpan<T extends SentrySpan>(span: T): T;
|
|
105
|
+
/**
|
|
106
|
+
* Options for `Sentry.init` that both sides of an app share, or `undefined`
|
|
107
|
+
* when `dsn` is not a usable DSN, which turns reporting off. Spread them
|
|
108
|
+
* into `init` and add the app's own, such as the browser's `tunnel`.
|
|
109
|
+
*/
|
|
110
|
+
export declare function sentryOptions(options: {
|
|
111
|
+
dsn: string | undefined;
|
|
112
|
+
environment?: string;
|
|
113
|
+
release?: string;
|
|
114
|
+
}): SentrySharedOptions | undefined;
|
|
115
|
+
/**
|
|
116
|
+
* A copy of a browser's request to the app's Sentry tunnel route, with only
|
|
117
|
+
* the headers Sentry may see: the body's type and length and the user agent.
|
|
118
|
+
* Hand it to the SDK's tunnel handler instead of the original. The SDK
|
|
119
|
+
* passes `X-Forwarded-For` (which nginx sets to the visitor's IP) on to
|
|
120
|
+
* Sentry, and the referer with its query string; this keeps both here.
|
|
121
|
+
*/
|
|
122
|
+
export declare function sentryTunnelRequest(request: Request): Promise<Request>;
|
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Sentry error reporting, shared by an app's browser and server setup. No
|
|
3
|
+
* Sentry import: the app passes `sentryOptions` to its own SDK's `init`, so
|
|
4
|
+
* this package needs no Sentry dependency. The types below are the parts of
|
|
5
|
+
* Sentry's events, spans and breadcrumbs the scrubbers touch.
|
|
6
|
+
*
|
|
7
|
+
* Reports carry no cookies, tokens, request bodies, query strings or the
|
|
8
|
+
* visitor's IP address. The SDK is told not to collect them
|
|
9
|
+
* (`dataCollection`), and the scrubbers remove them again before anything
|
|
10
|
+
* is sent, in case an integration adds them anyway.
|
|
11
|
+
*/
|
|
12
|
+
/** Request headers a report may carry. Every other header stays out. */
|
|
13
|
+
const REPORTED_HEADERS = new Set(["user-agent"]);
|
|
14
|
+
/**
|
|
15
|
+
* Span attributes a report never carries: the visitor's address, the query
|
|
16
|
+
* string, and every request and response header but the user agent.
|
|
17
|
+
*/
|
|
18
|
+
const DROPPED_SPAN_ATTRIBUTE = /^(client\.address|http\.client_ip|url\.query|user\.|http\.request\.header\.(?!user_agent$)|http\.response\.header\.)/;
|
|
19
|
+
/** Span attributes that hold a URL, kept without its query string. */
|
|
20
|
+
const URL_SPAN_ATTRIBUTES = ["url.full", "http.url", "http.target"];
|
|
21
|
+
/** Breadcrumb data fields that hold a URL (fetch, XHR, navigation). */
|
|
22
|
+
const URL_BREADCRUMB_FIELDS = ["url", "from", "to"];
|
|
23
|
+
/**
|
|
24
|
+
* True for a DSN Sentry can use: an absolute http(s) URL. An unset value, an
|
|
25
|
+
* empty one and an undefined Azure variable (written literally as
|
|
26
|
+
* `$(NAME)`) all turn reporting off, as in the webapi.
|
|
27
|
+
*/
|
|
28
|
+
export function isSentryDsn(value) {
|
|
29
|
+
if (!value) {
|
|
30
|
+
return false;
|
|
31
|
+
}
|
|
32
|
+
try {
|
|
33
|
+
const { protocol } = new URL(value);
|
|
34
|
+
return protocol === "https:" || protocol === "http:";
|
|
35
|
+
}
|
|
36
|
+
catch {
|
|
37
|
+
return false;
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
/** The URL without its query string and fragment. */
|
|
41
|
+
function withoutQuery(url) {
|
|
42
|
+
const end = url.search(/[?#]/);
|
|
43
|
+
return end === -1 ? url : url.slice(0, end);
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* Removes what a report must not carry from an error event: cookies, the
|
|
47
|
+
* request body, query strings, environment, headers other than the user
|
|
48
|
+
* agent, the visitor's IP and console breadcrumbs. A stack frame in one of
|
|
49
|
+
* the page's inline scripts is named after the page's URL, so frames lose
|
|
50
|
+
* their query string too. Changes the event in place and returns it, as
|
|
51
|
+
* `beforeSend` expects.
|
|
52
|
+
*/
|
|
53
|
+
export function scrubSentryEvent(event) {
|
|
54
|
+
const { request } = event;
|
|
55
|
+
if (request) {
|
|
56
|
+
delete request.cookies;
|
|
57
|
+
delete request.data;
|
|
58
|
+
delete request.query_string;
|
|
59
|
+
delete request.env;
|
|
60
|
+
if (request.url) {
|
|
61
|
+
request.url = withoutQuery(request.url);
|
|
62
|
+
}
|
|
63
|
+
if (request.headers) {
|
|
64
|
+
request.headers = Object.fromEntries(Object.entries(request.headers).filter(([name]) => REPORTED_HEADERS.has(name.toLowerCase())));
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
if (event.user) {
|
|
68
|
+
delete event.user.ip_address;
|
|
69
|
+
}
|
|
70
|
+
for (const value of event.exception?.values ?? []) {
|
|
71
|
+
for (const frame of value.stacktrace?.frames ?? []) {
|
|
72
|
+
if (frame.filename) {
|
|
73
|
+
frame.filename = withoutQuery(frame.filename);
|
|
74
|
+
}
|
|
75
|
+
if (frame.abs_path) {
|
|
76
|
+
frame.abs_path = withoutQuery(frame.abs_path);
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
if (event.breadcrumbs) {
|
|
81
|
+
event.breadcrumbs = event.breadcrumbs.flatMap((breadcrumb) => {
|
|
82
|
+
const kept = scrubSentryBreadcrumb(breadcrumb);
|
|
83
|
+
return kept ? [kept] : [];
|
|
84
|
+
});
|
|
85
|
+
}
|
|
86
|
+
return event;
|
|
87
|
+
}
|
|
88
|
+
/**
|
|
89
|
+
* Drops console breadcrumbs, since a console line can hold anything (the
|
|
90
|
+
* apps' request log has the visitor's IP), and takes the query string off
|
|
91
|
+
* the URLs of the rest. For `beforeBreadcrumb`.
|
|
92
|
+
*/
|
|
93
|
+
export function scrubSentryBreadcrumb(breadcrumb) {
|
|
94
|
+
if (breadcrumb.category === "console") {
|
|
95
|
+
return null;
|
|
96
|
+
}
|
|
97
|
+
const { data } = breadcrumb;
|
|
98
|
+
if (data) {
|
|
99
|
+
for (const field of URL_BREADCRUMB_FIELDS) {
|
|
100
|
+
const value = data[field];
|
|
101
|
+
if (typeof value === "string") {
|
|
102
|
+
data[field] = withoutQuery(value);
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
return breadcrumb;
|
|
107
|
+
}
|
|
108
|
+
/**
|
|
109
|
+
* Removes the visitor's address, query strings and headers other than the
|
|
110
|
+
* user agent from a span's attributes, and the query string from its URLs.
|
|
111
|
+
* For `beforeSendSpan`.
|
|
112
|
+
*/
|
|
113
|
+
export function scrubSentrySpan(span) {
|
|
114
|
+
const { attributes } = span;
|
|
115
|
+
if (!attributes) {
|
|
116
|
+
return span;
|
|
117
|
+
}
|
|
118
|
+
for (const key of Object.keys(attributes)) {
|
|
119
|
+
if (DROPPED_SPAN_ATTRIBUTE.test(key)) {
|
|
120
|
+
delete attributes[key];
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
for (const key of URL_SPAN_ATTRIBUTES) {
|
|
124
|
+
const value = attributes[key];
|
|
125
|
+
if (typeof value === "string") {
|
|
126
|
+
attributes[key] = withoutQuery(value);
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
return span;
|
|
130
|
+
}
|
|
131
|
+
/**
|
|
132
|
+
* Options for `Sentry.init` that both sides of an app share, or `undefined`
|
|
133
|
+
* when `dsn` is not a usable DSN, which turns reporting off. Spread them
|
|
134
|
+
* into `init` and add the app's own, such as the browser's `tunnel`.
|
|
135
|
+
*/
|
|
136
|
+
export function sentryOptions(options) {
|
|
137
|
+
if (!isSentryDsn(options.dsn)) {
|
|
138
|
+
return undefined;
|
|
139
|
+
}
|
|
140
|
+
return {
|
|
141
|
+
dsn: options.dsn,
|
|
142
|
+
environment: options.environment,
|
|
143
|
+
release: options.release,
|
|
144
|
+
tracesSampleRate: 0.1,
|
|
145
|
+
dataCollection: {
|
|
146
|
+
userInfo: false,
|
|
147
|
+
cookies: false,
|
|
148
|
+
httpHeaders: { allow: [...REPORTED_HEADERS] },
|
|
149
|
+
httpBodies: [],
|
|
150
|
+
urlQueryParams: false,
|
|
151
|
+
stackFrameVariables: false,
|
|
152
|
+
},
|
|
153
|
+
beforeSend: scrubSentryEvent,
|
|
154
|
+
beforeSendSpan: scrubSentrySpan,
|
|
155
|
+
beforeBreadcrumb: scrubSentryBreadcrumb,
|
|
156
|
+
beforeSendLog: () => null,
|
|
157
|
+
};
|
|
158
|
+
}
|
|
159
|
+
/** Request headers a Sentry tunnel passes on to Sentry. */
|
|
160
|
+
const TUNNEL_HEADERS = ["content-type", "user-agent"];
|
|
161
|
+
/**
|
|
162
|
+
* A copy of a browser's request to the app's Sentry tunnel route, with only
|
|
163
|
+
* the headers Sentry may see: the body's type and length and the user agent.
|
|
164
|
+
* Hand it to the SDK's tunnel handler instead of the original. The SDK
|
|
165
|
+
* passes `X-Forwarded-For` (which nginx sets to the visitor's IP) on to
|
|
166
|
+
* Sentry, and the referer with its query string; this keeps both here.
|
|
167
|
+
*/
|
|
168
|
+
export async function sentryTunnelRequest(request) {
|
|
169
|
+
const body = await request.arrayBuffer();
|
|
170
|
+
const headers = new Headers({ "content-length": String(body.byteLength) });
|
|
171
|
+
for (const name of TUNNEL_HEADERS) {
|
|
172
|
+
const value = request.headers.get(name);
|
|
173
|
+
if (value) {
|
|
174
|
+
headers.set(name, value);
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
return new Request(request.url, { method: request.method, headers, body });
|
|
178
|
+
}
|
package/dist/theme/index.d.ts
CHANGED
|
@@ -41,6 +41,17 @@ export declare function themeNeedsClientBootstrap(theme: Theme): boolean;
|
|
|
41
41
|
* Applies or removes the `dark` class on `document.documentElement`.
|
|
42
42
|
*/
|
|
43
43
|
export declare function applyDarkClass(isDark: boolean): void;
|
|
44
|
+
/**
|
|
45
|
+
* The named theme to show: `raw` when it is one of `names`, else `fallback`.
|
|
46
|
+
* A named theme is a whole look, picked with `data-theme` on `<html>`, and
|
|
47
|
+
* each has a light and a dark mode; it is not the `Theme` preference above.
|
|
48
|
+
* The names belong to the app's UI library, so the app passes them in.
|
|
49
|
+
*/
|
|
50
|
+
export declare function resolveThemeName<TName extends string>(raw: string | null | undefined, names: readonly TName[], fallback: TName): TName;
|
|
51
|
+
/**
|
|
52
|
+
* Sets the named theme on `document.documentElement` as `data-theme`.
|
|
53
|
+
*/
|
|
54
|
+
export declare function applyThemeName(themeName: string): void;
|
|
44
55
|
/**
|
|
45
56
|
* Inline script for first paint when preference is `system` (or legacy localStorage-only).
|
|
46
57
|
* `storageKey` is both the localStorage key and the cookie name unless
|
package/dist/theme/index.js
CHANGED
|
@@ -54,6 +54,21 @@ export function applyDarkClass(isDark) {
|
|
|
54
54
|
root.classList.remove("dark");
|
|
55
55
|
}
|
|
56
56
|
}
|
|
57
|
+
/**
|
|
58
|
+
* The named theme to show: `raw` when it is one of `names`, else `fallback`.
|
|
59
|
+
* A named theme is a whole look, picked with `data-theme` on `<html>`, and
|
|
60
|
+
* each has a light and a dark mode; it is not the `Theme` preference above.
|
|
61
|
+
* The names belong to the app's UI library, so the app passes them in.
|
|
62
|
+
*/
|
|
63
|
+
export function resolveThemeName(raw, names, fallback) {
|
|
64
|
+
return names.find((name) => name === raw) ?? fallback;
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
67
|
+
* Sets the named theme on `document.documentElement` as `data-theme`.
|
|
68
|
+
*/
|
|
69
|
+
export function applyThemeName(themeName) {
|
|
70
|
+
document.documentElement.dataset.theme = themeName;
|
|
71
|
+
}
|
|
57
72
|
/**
|
|
58
73
|
* A JS string literal for an inline `<script>`: JSON-quoted, with `<`
|
|
59
74
|
* escaped so the text can never close the script tag.
|
package/dist/theme/react.d.ts
CHANGED
|
@@ -14,6 +14,19 @@ type ThemeProviderProps = {
|
|
|
14
14
|
/** Saves the preference for SSR, normally a server function setting the cookie. */
|
|
15
15
|
persistTheme: (theme: Theme) => unknown;
|
|
16
16
|
onResolvedIsDarkChange?: (isDark: boolean) => void;
|
|
17
|
+
/**
|
|
18
|
+
* The named themes a visitor may pick from, for an app with a theme
|
|
19
|
+
* picker. A named theme is a whole look (`data-theme` on `<html>`), each
|
|
20
|
+
* with a light and a dark mode. Leave out for an app with one fixed theme.
|
|
21
|
+
*/
|
|
22
|
+
themeNames?: readonly string[];
|
|
23
|
+
/**
|
|
24
|
+
* The named theme the server rendered on `<html>`, from `getThemeName`.
|
|
25
|
+
* Pass it with `themeNames`.
|
|
26
|
+
*/
|
|
27
|
+
initialThemeName?: string;
|
|
28
|
+
/** Saves the named theme for SSR, normally a server function setting the cookie. */
|
|
29
|
+
persistThemeName?: (themeName: string) => unknown;
|
|
17
30
|
};
|
|
18
31
|
type ThemeProviderState = {
|
|
19
32
|
/** The preference: light, dark or system. */
|
|
@@ -30,13 +43,25 @@ type ThemeProviderState = {
|
|
|
30
43
|
resolvedTheme: "light" | "dark";
|
|
31
44
|
/** False on the server and the first client render, so their markup matches. */
|
|
32
45
|
mounted: boolean;
|
|
46
|
+
/** The named themes a visitor may pick from. Empty when the app has one fixed theme. */
|
|
47
|
+
themeNames: readonly string[];
|
|
48
|
+
/** The named theme shown. Undefined when the app offers none. */
|
|
49
|
+
themeName: string | undefined;
|
|
50
|
+
/**
|
|
51
|
+
* Shows a named theme (`data-theme` on `<html>`) and saves it with
|
|
52
|
+
* `persistThemeName`. A name that is not in `themeNames` is ignored.
|
|
53
|
+
*/
|
|
54
|
+
setThemeName: (themeName: string) => void;
|
|
33
55
|
};
|
|
34
56
|
/**
|
|
35
57
|
* Manages theme preference (localStorage + cookie) and syncs the `dark` class on `<html>`.
|
|
58
|
+
* With `themeNames` it also holds the named theme a visitor picked and sets
|
|
59
|
+
* it as `data-theme` on `<html>`.
|
|
36
60
|
*/
|
|
37
|
-
export declare function ThemeProvider({ children, initialTheme, initialIsDark, storageKey, persistTheme, onResolvedIsDarkChange, }: ThemeProviderProps): React.JSX.Element;
|
|
61
|
+
export declare function ThemeProvider({ children, initialTheme, initialIsDark, storageKey, persistTheme, onResolvedIsDarkChange, themeNames, initialThemeName, persistThemeName, }: ThemeProviderProps): React.JSX.Element;
|
|
38
62
|
/**
|
|
39
|
-
* Hook to access the theme preference, the theme shown, and the setters
|
|
63
|
+
* Hook to access the theme preference, the theme shown, and the setters,
|
|
64
|
+
* plus the named theme and its setter when the app offers a picker.
|
|
40
65
|
*/
|
|
41
66
|
export declare const useTheme: () => ThemeProviderState;
|
|
42
67
|
export {};
|
package/dist/theme/react.js
CHANGED
|
@@ -1,12 +1,17 @@
|
|
|
1
1
|
import { jsx as _jsx } from "react/jsx-runtime";
|
|
2
2
|
import * as React from "react";
|
|
3
|
-
import { applyDarkClass, resolveIsDark, SYSTEM_DARK_WHEN_UNKNOWN, ThemeSchema, } from "./index.js";
|
|
3
|
+
import { applyDarkClass, applyThemeName, resolveIsDark, SYSTEM_DARK_WHEN_UNKNOWN, ThemeSchema, } from "./index.js";
|
|
4
|
+
/** One array for "no named themes", so the context value keeps its identity. */
|
|
5
|
+
const NO_THEME_NAMES = [];
|
|
4
6
|
const initialState = {
|
|
5
7
|
theme: "system",
|
|
6
8
|
setTheme: () => null,
|
|
7
9
|
toggleTheme: () => null,
|
|
8
10
|
resolvedTheme: SYSTEM_DARK_WHEN_UNKNOWN ? "dark" : "light",
|
|
9
11
|
mounted: false,
|
|
12
|
+
themeNames: NO_THEME_NAMES,
|
|
13
|
+
themeName: undefined,
|
|
14
|
+
setThemeName: () => null,
|
|
10
15
|
};
|
|
11
16
|
/**
|
|
12
17
|
* One context for every copy of this module. TanStack Start bundles this
|
|
@@ -51,9 +56,14 @@ function storeTheme(storageKey, theme) {
|
|
|
51
56
|
}
|
|
52
57
|
/**
|
|
53
58
|
* Manages theme preference (localStorage + cookie) and syncs the `dark` class on `<html>`.
|
|
59
|
+
* With `themeNames` it also holds the named theme a visitor picked and sets
|
|
60
|
+
* it as `data-theme` on `<html>`.
|
|
54
61
|
*/
|
|
55
|
-
export function ThemeProvider({ children, initialTheme, initialIsDark = SYSTEM_DARK_WHEN_UNKNOWN, storageKey, persistTheme, onResolvedIsDarkChange, }) {
|
|
62
|
+
export function ThemeProvider({ children, initialTheme, initialIsDark = SYSTEM_DARK_WHEN_UNKNOWN, storageKey, persistTheme, onResolvedIsDarkChange, themeNames = NO_THEME_NAMES, initialThemeName, persistThemeName, }) {
|
|
56
63
|
const [theme, setThemeState] = React.useState(initialTheme);
|
|
64
|
+
// The server rendered the first one on <html>; after that `setThemeName`
|
|
65
|
+
// sets the attribute itself.
|
|
66
|
+
const [themeName, setThemeNameState] = React.useState(initialThemeName);
|
|
57
67
|
// The OS preference; undefined until mounted.
|
|
58
68
|
const [systemPrefersDark, setSystemPrefersDark] = React.useState(undefined);
|
|
59
69
|
const mounted = systemPrefersDark !== undefined;
|
|
@@ -63,6 +73,8 @@ export function ThemeProvider({ children, initialTheme, initialIsDark = SYSTEM_D
|
|
|
63
73
|
persistRef.current = persistTheme;
|
|
64
74
|
const onResolvedIsDarkChangeRef = React.useRef(onResolvedIsDarkChange);
|
|
65
75
|
onResolvedIsDarkChangeRef.current = onResolvedIsDarkChange;
|
|
76
|
+
const persistThemeNameRef = React.useRef(persistThemeName);
|
|
77
|
+
persistThemeNameRef.current = persistThemeName;
|
|
66
78
|
React.useEffect(() => {
|
|
67
79
|
const storedTheme = readStoredTheme(storageKey);
|
|
68
80
|
if (!storedTheme) {
|
|
@@ -102,11 +114,22 @@ export function ThemeProvider({ children, initialTheme, initialIsDark = SYSTEM_D
|
|
|
102
114
|
toggleTheme: () => setTheme(resolveIsDark(theme, getSystemPrefersDark()) ? "light" : "dark"),
|
|
103
115
|
resolvedTheme: isDark ? "dark" : "light",
|
|
104
116
|
mounted,
|
|
117
|
+
themeNames,
|
|
118
|
+
themeName,
|
|
119
|
+
setThemeName: (newThemeName) => {
|
|
120
|
+
if (!themeNames.includes(newThemeName)) {
|
|
121
|
+
return;
|
|
122
|
+
}
|
|
123
|
+
applyThemeName(newThemeName);
|
|
124
|
+
void persistThemeNameRef.current?.(newThemeName);
|
|
125
|
+
setThemeNameState(newThemeName);
|
|
126
|
+
},
|
|
105
127
|
};
|
|
106
|
-
}, [theme, storageKey, isDark, mounted]);
|
|
128
|
+
}, [theme, storageKey, isDark, mounted, themeNames, themeName]);
|
|
107
129
|
return (_jsx(ThemeProviderContext.Provider, { value: value, children: children }));
|
|
108
130
|
}
|
|
109
131
|
/**
|
|
110
|
-
* Hook to access the theme preference, the theme shown, and the setters
|
|
132
|
+
* Hook to access the theme preference, the theme shown, and the setters,
|
|
133
|
+
* plus the named theme and its setter when the app offers a picker.
|
|
111
134
|
*/
|
|
112
135
|
export const useTheme = () => React.useContext(ThemeProviderContext);
|
package/dist/theme/server.d.ts
CHANGED
|
@@ -10,3 +10,15 @@ export declare function getThemeContext(cookieName: string): ThemeContext;
|
|
|
10
10
|
* Persists theme preference in an HTTP cookie for SSR on the next request.
|
|
11
11
|
*/
|
|
12
12
|
export declare function setThemeCookie(cookieName: string, theme: Theme): void;
|
|
13
|
+
/**
|
|
14
|
+
* Reads the named theme a visitor picked from the `cookieName` cookie: its
|
|
15
|
+
* value when it is one of `names`, else `fallback`. The root route renders it
|
|
16
|
+
* as `data-theme` on `<html>`. The cookie is the only place it is kept, so
|
|
17
|
+
* the server always knows it and the page needs no first-paint script for it.
|
|
18
|
+
*/
|
|
19
|
+
export declare function getThemeName<TName extends string>(cookieName: string, names: readonly TName[], fallback: TName): TName;
|
|
20
|
+
/**
|
|
21
|
+
* Persists the named theme in an HTTP cookie for SSR on the next request.
|
|
22
|
+
* The app's server function checks the name against its own list first.
|
|
23
|
+
*/
|
|
24
|
+
export declare function setThemeNameCookie(cookieName: string, themeName: string): void;
|
package/dist/theme/server.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { getCookie, getRequestHeader, setCookie, } from "@tanstack/react-start/server";
|
|
2
|
-
import { resolveIsDark, SYSTEM_DARK_WHEN_UNKNOWN, ThemeSchema, } from "./index.js";
|
|
2
|
+
import { resolveIsDark, resolveThemeName, SYSTEM_DARK_WHEN_UNKNOWN, ThemeSchema, } from "./index.js";
|
|
3
3
|
/**
|
|
4
4
|
* Reads theme preference from the `cookieName` cookie and resolves dark mode
|
|
5
5
|
* for SSR. For a `system` preference it uses `Sec-CH-Prefers-Color-Scheme`,
|
|
@@ -19,13 +19,31 @@ export function getThemeContext(cookieName) {
|
|
|
19
19
|
const isDark = resolveIsDark(theme, prefersDark);
|
|
20
20
|
return { theme, isDark };
|
|
21
21
|
}
|
|
22
|
+
/** A year, for the whole site. Readable by script: the bootstrap script reads the preference. */
|
|
23
|
+
const THEME_COOKIE_OPTIONS = {
|
|
24
|
+
path: "/",
|
|
25
|
+
maxAge: 60 * 60 * 24 * 365,
|
|
26
|
+
sameSite: "lax",
|
|
27
|
+
};
|
|
22
28
|
/**
|
|
23
29
|
* Persists theme preference in an HTTP cookie for SSR on the next request.
|
|
24
30
|
*/
|
|
25
31
|
export function setThemeCookie(cookieName, theme) {
|
|
26
|
-
setCookie(cookieName, theme,
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
32
|
+
setCookie(cookieName, theme, THEME_COOKIE_OPTIONS);
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* Reads the named theme a visitor picked from the `cookieName` cookie: its
|
|
36
|
+
* value when it is one of `names`, else `fallback`. The root route renders it
|
|
37
|
+
* as `data-theme` on `<html>`. The cookie is the only place it is kept, so
|
|
38
|
+
* the server always knows it and the page needs no first-paint script for it.
|
|
39
|
+
*/
|
|
40
|
+
export function getThemeName(cookieName, names, fallback) {
|
|
41
|
+
return resolveThemeName(getCookie(cookieName), names, fallback);
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Persists the named theme in an HTTP cookie for SSR on the next request.
|
|
45
|
+
* The app's server function checks the name against its own list first.
|
|
46
|
+
*/
|
|
47
|
+
export function setThemeNameCookie(cookieName, themeName) {
|
|
48
|
+
setCookie(cookieName, themeName, THEME_COOKIE_OPTIONS);
|
|
31
49
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "singularity-core",
|
|
3
|
-
"version": "0.17.
|
|
3
|
+
"version": "0.17.2",
|
|
4
4
|
"description": "Shared non-UI code for Singularity TanStack Start apps: auth sessions, API client middleware, API schemas, paging, route data, images, formatting, HTTP helpers, theme, cookie notice, SEO, security headers and telemetry.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"author": "Filip",
|