@bridgebrew/storage 0.0.0-stage → 0.0.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 bridgebrew
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,51 @@
1
+ // Storage's page in Settings (`settingsPage`): how a workspace's storage is made, read-only (./storage-page.tsx), from
2
+ // storage's own `GET /inventory` in the workspace Settings shows. Registered as the `storage.settings` factory, which
3
+ // the plugin manager draws in Settings and in storage's Settings tab: storage's browser entry is `_host`'s (one per
4
+ // page), so a screen of its own would never show in a workspace, a factory does. Its item is a domain's id.
5
+ import * as React from 'react';
6
+ import type { Context } from 'cordis';
7
+ import type {} from '@bridge/ui-renderer/client';
8
+ import { readJson, type FollowTarget } from '@bridge/ui';
9
+ import type { Inventory } from '../inventory.ts';
10
+ import { StoragePage } from './storage-page.tsx';
11
+
12
+ export const name = 'storage';
13
+ export const inject = ['slots'];
14
+
15
+ /** What the plugin manager draws a settings page with (its `settings-page.tsx`, `SettingsPageProps`): the fields this
16
+ * page reads. */
17
+ interface SettingsPageProps {
18
+ slug: string;
19
+ fetch: (input: string, init?: RequestInit) => Promise<Response>;
20
+ item?: string | undefined;
21
+ open: (item?: string) => void;
22
+ linkTo: (item?: string) => FollowTarget;
23
+ }
24
+
25
+ /** The page for the workspace `slug` names. */
26
+ export function StorageSettings({ slug, fetch, item, open, linkTo }: SettingsPageProps) {
27
+ const load = React.useCallback(
28
+ async () =>
29
+ (await readJson(
30
+ await fetch(`/${encodeURIComponent(slug)}/api/storage/inventory`, { cache: 'no-store' }),
31
+ )) as Inventory,
32
+ [slug, fetch],
33
+ );
34
+ return <StoragePage load={load} item={item} open={open} linkTo={linkTo} />;
35
+ }
36
+
37
+ export function apply(ctx: Context) {
38
+ // The factory `<key>.settings` the plugin manager draws in Settings (its `settings-page.tsx`).
39
+ // oxlint-disable-next-line bridge/no-new-unchecked-cast -- typing: the slot map types factory names statically, a settings page's is `<key>.settings`
40
+ const { slots } = ctx as unknown as {
41
+ slots: {
42
+ registerFactory(
43
+ options: { name: string; scope: 'root' },
44
+ component: (props: SettingsPageProps) => React.ReactNode,
45
+ ): () => void;
46
+ };
47
+ };
48
+ slots.registerFactory({ name: `${name}.settings`, scope: 'root' }, (props) => (
49
+ <StorageSettings {...props} />
50
+ ));
51
+ }
@@ -0,0 +1,70 @@
1
+ // What the Storage screen shows of the inventory (`GET /inventory`, ./inventory.ts), as words: the domains grouped by
2
+ // their plugin, a search over them, and the labels of a domain's kind, writers, count and the backend's sizes.
3
+ import type { DomainInventory, DomainKind, Inventory } from '../inventory.ts';
4
+ import { formatNumber } from '@bridge/ui';
5
+
6
+ /** Each kind's name and icon (the kit's `Icon` set). */
7
+ export const kinds: Record<DomainKind, { label: string; icon: string }> = {
8
+ objects: { label: 'Objects', icon: 'box' },
9
+ facets: { label: 'Facets', icon: 'tag' },
10
+ log: { label: 'Log', icon: 'scroll-text' },
11
+ plain: { label: 'Plain', icon: 'file-text' },
12
+ shared: { label: 'Shared', icon: 'globe' },
13
+ };
14
+
15
+ /** The domains whose id, kind or a reference's domain holds `query` (any case), grouped by plugin, the plugins and the
16
+ * domains in id order (the inventory's). */
17
+ export const groupsOf = (domains: readonly DomainInventory[], query = '') => {
18
+ const words = query.trim().toLowerCase();
19
+ const groups = new Map<string, DomainInventory[]>();
20
+ for (const domain of domains) {
21
+ const text = [domain.id, domain.kind, ...domain.references.map((each) => each.domain)]
22
+ .join(' ')
23
+ .toLowerCase();
24
+ if (words && !text.includes(words)) continue;
25
+ const group = groups.get(domain.plugin) ?? [];
26
+ group.push(domain);
27
+ groups.set(domain.plugin, group);
28
+ }
29
+ return [...groups].map(([plugin, each]) => ({ plugin, domains: each }));
30
+ };
31
+
32
+ /** `1,234`: a count with its thousands apart. */
33
+ const number = (value: number) => formatNumber(value);
34
+
35
+ /** What a domain holds, in a few words: `12 objects (3 archived)`, `4 facets`, `2 keys`; none when not counted. */
36
+ export const countLabel = ({ kind, count }: Pick<DomainInventory, 'kind' | 'count'>) => {
37
+ if (!count) return undefined;
38
+ const { total, archived } = count;
39
+ const noun =
40
+ kind === 'objects'
41
+ ? total === 1
42
+ ? 'object'
43
+ : 'objects'
44
+ : kind === 'facets'
45
+ ? total === 1
46
+ ? 'facet'
47
+ : 'facets'
48
+ : total === 1
49
+ ? 'key'
50
+ : 'keys';
51
+ return `${number(total)} ${noun}${archived ? ` (${number(archived)} archived)` : ''}`;
52
+ };
53
+
54
+ /** Who writes an object domain (research-052 D3). */
55
+ export const writersLabel = (writers: DomainInventory['writers']) =>
56
+ writers === 'workspace' ? 'Any plugin of the workspace, under its rules' : 'Its plugin only';
57
+
58
+ /** `1.2 MiB`. */
59
+ export const bytesLabel = (bytes: number) =>
60
+ bytes < 1024
61
+ ? `${bytes} B`
62
+ : bytes < 1048576
63
+ ? `${(bytes / 1024).toFixed(1)} KiB`
64
+ : bytes < 1073741824
65
+ ? `${(bytes / 1048576).toFixed(1)} MiB`
66
+ : `${(bytes / 1073741824).toFixed(1)} GiB`;
67
+
68
+ /** What the backend's files take on disk, summed; none when it did not tell (a database server tells none). */
69
+ export const totalBytes = ({ sizes }: Inventory['backend']) =>
70
+ sizes && sizes.length > 0 ? sizes.reduce((sum, { bytes }) => sum + bytes, 0) : undefined;
@@ -0,0 +1,340 @@
1
+ // The Storage page: how the workspace's storage is made, read-only, from `GET /inventory` (./inventory.ts). The list
2
+ // (left) groups the declared domains by plugin, with a search; beside it, the domain the item names (its kind, version,
3
+ // privacy, writers, rule names, count, references both ways, indexes and search paths), or, with none, the backend (its
4
+ // plugin, the size of its files) and the totals. Metadata only: no value of any domain is shown.
5
+ // The page makes no assumption on its frame: the frame gives how to load the inventory, the domain shown (`item`), how
6
+ // to open one from a row (`open`), and where a link to a domain goes (`linkTo`, an item of the window's screen by
7
+ // default). Its frames are the plugin manager's (./browser.tsx, `settingsPage`): Settings, and storage's Settings tab.
8
+ import * as React from 'react';
9
+ import {
10
+ Badge,
11
+ Button,
12
+ Detail,
13
+ DetailHeader,
14
+ DetailSubtitle,
15
+ DetailTitle,
16
+ EmptyState,
17
+ Icon,
18
+ Input,
19
+ List,
20
+ MultiPane,
21
+ ListGroup,
22
+ ListItem,
23
+ ListSkeleton,
24
+ Pane,
25
+ PaneBody,
26
+ PaneFooter,
27
+ PaneHeader,
28
+ Properties,
29
+ PropertyRow,
30
+ ScreenLink,
31
+ Section,
32
+ type FollowTarget,
33
+ formatNumber,
34
+ } from '@bridge/ui';
35
+ import type { DomainInventory, Inventory } from '../inventory.ts';
36
+ import {
37
+ bytesLabel,
38
+ countLabel,
39
+ groupsOf,
40
+ kinds,
41
+ totalBytes,
42
+ writersLabel,
43
+ } from './storage-model.ts';
44
+
45
+ export interface StoragePageProps {
46
+ /** The inventory, read again on Retry. */
47
+ load: () => Promise<Inventory>;
48
+ /** The domain shown beside the list, its id; none: the backend. */
49
+ item?: string | undefined;
50
+ /** Opens a domain from its row (a plain click or Enter; ⌘ and middle clicks follow the shell's rule on their own). */
51
+ open: (id: string) => void;
52
+ /** Where a link to domain `id` goes: an item of the screen its window shows by default. */
53
+ linkTo?: (id: string) => FollowTarget;
54
+ }
55
+
56
+ const messageOf = (cause: unknown) => (cause instanceof Error ? cause.message : String(cause));
57
+
58
+ export function StoragePage({
59
+ load,
60
+ item,
61
+ open,
62
+ linkTo = (id) => ({ item: id }),
63
+ }: StoragePageProps) {
64
+ const [inventory, setInventory] = React.useState<Inventory>();
65
+ const [failure, setFailure] = React.useState<string>();
66
+ const [attempt, setAttempt] = React.useState(0);
67
+ const [query, setQuery] = React.useState('');
68
+ React.useEffect(() => {
69
+ let current = true;
70
+ setFailure(undefined);
71
+ load().then(
72
+ (read) => current && setInventory(read),
73
+ (cause: unknown) => current && setFailure(messageOf(cause)),
74
+ );
75
+ return () => {
76
+ current = false;
77
+ };
78
+ }, [load, attempt]);
79
+
80
+ const groups = inventory ? groupsOf(inventory.domains, query) : [];
81
+ const shown = inventory?.domains.find((each) => each.id === item);
82
+ const link = (id: string) => <ScreenLink to={linkTo(id)}>{id}</ScreenLink>;
83
+
84
+ const body = failure ? (
85
+ <EmptyState role="alert" title="Storage could not be read">
86
+ <p>{failure}</p>
87
+ <Button variant="outline" onClick={() => setAttempt((n) => n + 1)}>
88
+ Retry
89
+ </Button>
90
+ </EmptyState>
91
+ ) : inventory === undefined ? (
92
+ <ListSkeleton />
93
+ ) : groups.length === 0 ? (
94
+ <EmptyState
95
+ icon={<Icon name="database" size={20} />}
96
+ title={query ? 'No domain matches' : 'No domain declared'}
97
+ >
98
+ {query !== '' && (
99
+ <Button variant="ghost" onClick={() => setQuery('')}>
100
+ Clear the search
101
+ </Button>
102
+ )}
103
+ </EmptyState>
104
+ ) : (
105
+ <List
106
+ variant="records"
107
+ aria-label="Domains"
108
+ {...(item !== undefined && { openKey: item })}
109
+ onOpen={open}
110
+ >
111
+ {groups.map(({ plugin, domains }) => (
112
+ <ListGroup key={plugin} label={plugin} variant="records" collapsible count={domains.length}>
113
+ {domains.map((domain) => (
114
+ <ListItem
115
+ key={domain.id}
116
+ value={domain.id}
117
+ textValue={domain.id}
118
+ data-domain={domain.id}
119
+ leading={<Icon name={kinds[domain.kind].icon} size={14} />}
120
+ properties={
121
+ <>
122
+ {domain.private && <Badge>Private</Badge>}
123
+ {domain.writers === 'workspace' && <Badge>Open to writers</Badge>}
124
+ <span className="text-xs text-secondary">{kinds[domain.kind].label}</span>
125
+ </>
126
+ }
127
+ trailing={
128
+ domain.count && (
129
+ <span className="tabular-nums">{formatNumber(domain.count.total)}</span>
130
+ )
131
+ }
132
+ >
133
+ <span className="min-w-0 flex-1 truncate">{domain.name}</span>
134
+ </ListItem>
135
+ ))}
136
+ </ListGroup>
137
+ ))}
138
+ </List>
139
+ );
140
+
141
+ return (
142
+ <MultiPane
143
+ data-storage-page
144
+ storageKey="storage/storage/list@v1"
145
+ collapse={false}
146
+ defaultNavSize="40%"
147
+ nav={
148
+ <Pane aria-label="Domains">
149
+ <PaneHeader>
150
+ <Input
151
+ variant="outline"
152
+ size="default"
153
+ type="search"
154
+ aria-label="Search domains"
155
+ placeholder="Search domains"
156
+ icon={<Icon name="search" size={14} />}
157
+ value={query}
158
+ onChange={(event) => setQuery(event.currentTarget.value)}
159
+ onKeyDown={(event) => event.key === 'Escape' && setQuery('')}
160
+ />
161
+ </PaneHeader>
162
+ <PaneBody>{body}</PaneBody>
163
+ <PaneFooter role="status">
164
+ {inventory &&
165
+ `${inventory.domains.length} domain${inventory.domains.length === 1 ? '' : 's'} · ${
166
+ new Set(inventory.domains.map((each) => each.plugin)).size
167
+ } plugin${new Set(inventory.domains.map((each) => each.plugin)).size === 1 ? '' : 's'}`}
168
+ </PaneFooter>
169
+ </Pane>
170
+ }
171
+ main={
172
+ shown ? (
173
+ <DomainDetail key={shown.id} domain={shown} link={link} />
174
+ ) : item !== undefined && inventory ? (
175
+ <EmptyState fill icon={<Icon name="database" size={24} />} title="No such domain">
176
+ <p>
177
+ {item} is not declared in this workspace: its plugin is not loaded, or it was renamed.
178
+ </p>
179
+ </EmptyState>
180
+ ) : inventory ? (
181
+ <BackendDetail inventory={inventory} />
182
+ ) : null
183
+ }
184
+ />
185
+ );
186
+ }
187
+
188
+ /** The detail's frame: a title, a line under it, then its sections. */
189
+ function Page({
190
+ title,
191
+ subtitle,
192
+ label,
193
+ children,
194
+ }: {
195
+ title: string;
196
+ subtitle: React.ReactNode;
197
+ label: string;
198
+ children: React.ReactNode;
199
+ }) {
200
+ return (
201
+ <Detail aria-label={label} className="box-border w-full max-w-none gap-6 px-5 pt-5">
202
+ <DetailHeader>
203
+ <DetailTitle>
204
+ <Section size="lg" title={title} />
205
+ <DetailSubtitle className="flex items-center gap-1.5">{subtitle}</DetailSubtitle>
206
+ </DetailTitle>
207
+ </DetailHeader>
208
+ {children}
209
+ </Detail>
210
+ );
211
+ }
212
+
213
+ const rows = 'text-sm [&_[data-slot=property-label]]:text-secondary';
214
+
215
+ /** A domain's metadata. */
216
+ function DomainDetail({
217
+ domain,
218
+ link,
219
+ }: {
220
+ domain: DomainInventory;
221
+ link: (id: string) => React.ReactNode;
222
+ }) {
223
+ const kind = kinds[domain.kind];
224
+ const count = countLabel(domain);
225
+ return (
226
+ <Page
227
+ title={domain.name}
228
+ label={domain.id}
229
+ subtitle={
230
+ <>
231
+ <Icon name={kind.icon} size={14} />
232
+ {kind.label} · {domain.id}
233
+ </>
234
+ }
235
+ >
236
+ <Properties className={rows}>
237
+ <PropertyRow label="Plugin">{domain.plugin}</PropertyRow>
238
+ <PropertyRow label="Kind">{kind.label}</PropertyRow>
239
+ <PropertyRow label="Version">{domain.version}</PropertyRow>
240
+ <PropertyRow label="Private">
241
+ {domain.private
242
+ ? 'Yes: only its plugin reads it'
243
+ : 'No: any plugin of the workspace reads it'}
244
+ </PropertyRow>
245
+ {domain.writers !== undefined && (
246
+ <PropertyRow label="Writers">{writersLabel(domain.writers)}</PropertyRow>
247
+ )}
248
+ {domain.rules !== undefined && (
249
+ <PropertyRow label="Rules">
250
+ {domain.rules.length > 0 ? domain.rules.join(', ') : 'None'}
251
+ </PropertyRow>
252
+ )}
253
+ {domain.target !== undefined && (
254
+ <PropertyRow label="Attached to">{link(domain.target)}</PropertyRow>
255
+ )}
256
+ {domain.kind !== 'log' && <PropertyRow label="Holds">{count ?? 'Not counted'}</PropertyRow>}
257
+ </Properties>
258
+ <Section title="References" description="Its fields pointing to another domain">
259
+ {domain.references.length > 0 ? (
260
+ <Properties className={rows}>
261
+ {domain.references.map(({ field, domain: to }) => (
262
+ <PropertyRow key={field} label={field}>
263
+ {link(to)}
264
+ </PropertyRow>
265
+ ))}
266
+ </Properties>
267
+ ) : (
268
+ <p className="m-0 text-sm text-muted">None</p>
269
+ )}
270
+ </Section>
271
+ <Section title="Referenced by" description="Fields of other domains pointing here">
272
+ {domain.referencedBy.length > 0 ? (
273
+ <Properties className={rows}>
274
+ {domain.referencedBy.map(({ field, domain: from }) => (
275
+ <PropertyRow key={`${from}.${field}`} label={field}>
276
+ {link(from)}
277
+ </PropertyRow>
278
+ ))}
279
+ </Properties>
280
+ ) : (
281
+ <p className="m-0 text-sm text-muted">None</p>
282
+ )}
283
+ </Section>
284
+ {domain.kind === 'objects' && (
285
+ <Section
286
+ title="Indexes and search"
287
+ description="What the backend keeps to order and search it"
288
+ >
289
+ <Properties className={rows}>
290
+ <PropertyRow label="Indexes">
291
+ {domain.indexes?.length ? domain.indexes.join(', ') : 'None'}
292
+ </PropertyRow>
293
+ <PropertyRow label="Search">
294
+ {domain.search?.paths.length
295
+ ? `${domain.search.paths.join(', ')}${domain.search.trigram ? ' (trigram index)' : ''}`
296
+ : 'None'}
297
+ </PropertyRow>
298
+ </Properties>
299
+ </Section>
300
+ )}
301
+ </Page>
302
+ );
303
+ }
304
+
305
+ /** The backend, and what the domains add up to. */
306
+ function BackendDetail({ inventory }: { inventory: Inventory }) {
307
+ const { backend, domains } = inventory;
308
+ const total = totalBytes(backend);
309
+ return (
310
+ <Page
311
+ title="Storage"
312
+ label="Storage"
313
+ subtitle={
314
+ <>
315
+ <Icon name="database" size={14} />
316
+ {backend.plugin ?? 'Unknown backend'}
317
+ </>
318
+ }
319
+ >
320
+ <Properties className={rows}>
321
+ <PropertyRow label="Backend">{backend.plugin ?? 'Unknown'}</PropertyRow>
322
+ <PropertyRow label="On disk">
323
+ {total === undefined ? 'Not told' : bytesLabel(total)}
324
+ </PropertyRow>
325
+ <PropertyRow label="Domains">{domains.length}</PropertyRow>
326
+ </Properties>
327
+ {backend.sizes && backend.sizes.length > 0 && (
328
+ <Section title="Files" description="What each of the backend's files takes on disk">
329
+ <Properties className={rows}>
330
+ {backend.sizes.map(({ file, bytes }) => (
331
+ <PropertyRow key={file} label={file}>
332
+ {bytesLabel(bytes)}
333
+ </PropertyRow>
334
+ ))}
335
+ </Properties>
336
+ </Section>
337
+ )}
338
+ </Page>
339
+ );
340
+ }
@@ -0,0 +1,13 @@
1
+ {
2
+ "//": "The page (its tests are typed with the tests project): its services through the Bridge checkout this repository links (../../bridge), the contracts of the plugins it uses from their folders here.",
3
+ "extends": "../.bridge/tsconfig.browser.json",
4
+ "include": [
5
+ ".",
6
+ "../../bridge/packages/browser-boot/src/workspace.d.ts",
7
+ "../../bridge/vendor/types/client-build-environment.d.ts"
8
+ ],
9
+ "exclude": [
10
+ "./**/*.test.ts",
11
+ "./**/*.test.tsx"
12
+ ]
13
+ }