@designtools/comments 0.0.0-stage → 0.1.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/CHANGELOG.md +13 -0
- package/LICENSE +21 -0
- package/README.md +145 -2
- package/dist/adapter.d.ts +45 -0
- package/dist/adapter.js +177 -0
- package/dist/api.d.ts +20 -0
- package/dist/api.js +35 -0
- package/dist/cli.d.ts +19 -0
- package/dist/cli.js +216 -0
- package/dist/comments.d.ts +24 -0
- package/dist/comments.js +567 -0
- package/dist/css.d.ts +2 -0
- package/dist/css.js +2 -0
- package/dist/identity.d.ts +6 -0
- package/dist/identity.js +66 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.js +4 -0
- package/dist/server/handler.d.ts +45 -0
- package/dist/server/handler.js +169 -0
- package/dist/server/index.d.ts +11 -0
- package/dist/server/index.js +10 -0
- package/dist/server/memory.d.ts +6 -0
- package/dist/server/memory.js +81 -0
- package/dist/server/migrations.d.ts +17 -0
- package/dist/server/migrations.js +61 -0
- package/dist/server/postgres.d.ts +7 -0
- package/dist/server/postgres.js +100 -0
- package/dist/server/sql.d.ts +14 -0
- package/dist/server/sql.js +36 -0
- package/dist/types.d.ts +112 -0
- package/dist/types.js +5 -0
- package/dist/validate.d.ts +40 -0
- package/dist/validate.js +144 -0
- package/package.json +80 -3
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a comment is, shared by the browser, the route handler, the stores and the command line.
|
|
3
|
+
* No DOM and no Node here.
|
|
4
|
+
*/
|
|
5
|
+
/** What a comment is pinned to: a module, a section, an element, with a content field inside it. */
|
|
6
|
+
export interface Anchor {
|
|
7
|
+
/** "module", "section", "element". */
|
|
8
|
+
kind: string;
|
|
9
|
+
/** A stable id the page carries, such as "module:ComponentModulesHero:12". Empty when only the selector was recorded. */
|
|
10
|
+
key: string;
|
|
11
|
+
/** What people and screen readers hear: "Hero". */
|
|
12
|
+
label: string;
|
|
13
|
+
/** A content field inside it: "heading". */
|
|
14
|
+
field?: string;
|
|
15
|
+
/** A CSS selector, recorded for when there is no key, or it can't be found. */
|
|
16
|
+
selector: string;
|
|
17
|
+
}
|
|
18
|
+
export type ThreadStatus = "open" | "resolved";
|
|
19
|
+
/** Who wrote something: a name typed once and remembered by the browser, and a random id it made. Taken on trust. */
|
|
20
|
+
export interface Author {
|
|
21
|
+
name: string;
|
|
22
|
+
id: string;
|
|
23
|
+
}
|
|
24
|
+
export interface Comment {
|
|
25
|
+
id: string;
|
|
26
|
+
threadId: string;
|
|
27
|
+
authorName: string;
|
|
28
|
+
authorId: string;
|
|
29
|
+
/** Plain text, never HTML. */
|
|
30
|
+
body: string;
|
|
31
|
+
createdAt: string;
|
|
32
|
+
}
|
|
33
|
+
export interface Thread {
|
|
34
|
+
id: string;
|
|
35
|
+
/** The page's path, locale included: "/de/about". Kept up to date for a page with a key when it moves. */
|
|
36
|
+
path: string;
|
|
37
|
+
/** A stable id for the page, from `data-comment-page`, such as "page:about:3". It follows the page when its path changes. */
|
|
38
|
+
pageKey: string | null;
|
|
39
|
+
locale: string | null;
|
|
40
|
+
anchor: Anchor;
|
|
41
|
+
/** How wide the window was when the thread was started, in CSS px. */
|
|
42
|
+
viewportWidth: number | null;
|
|
43
|
+
/** The deployment it was left on, its branch and commit. */
|
|
44
|
+
deploymentUrl: string | null;
|
|
45
|
+
branch: string | null;
|
|
46
|
+
commit: string | null;
|
|
47
|
+
status: ThreadStatus;
|
|
48
|
+
createdAt: string;
|
|
49
|
+
createdBy: string;
|
|
50
|
+
resolvedAt: string | null;
|
|
51
|
+
resolvedBy: string | null;
|
|
52
|
+
/** Oldest first; the first is the thread's own. */
|
|
53
|
+
comments: Comment[];
|
|
54
|
+
}
|
|
55
|
+
/** Where the handler is running, so the tool can mark threads left on another branch. */
|
|
56
|
+
export interface Deployment {
|
|
57
|
+
url: string | null;
|
|
58
|
+
branch: string | null;
|
|
59
|
+
commit: string | null;
|
|
60
|
+
}
|
|
61
|
+
/** What the browser sends to start a thread. */
|
|
62
|
+
export interface NewThread {
|
|
63
|
+
path: string;
|
|
64
|
+
/** The page's stable id, where it has one. */
|
|
65
|
+
pageKey?: string | null;
|
|
66
|
+
locale: string | null;
|
|
67
|
+
anchor: Anchor;
|
|
68
|
+
viewportWidth: number | null;
|
|
69
|
+
body: string;
|
|
70
|
+
author: Author;
|
|
71
|
+
}
|
|
72
|
+
/** What a store is asked to keep for a new thread: the browser's part, and the deployment it came from. */
|
|
73
|
+
export interface CreateThread extends NewThread {
|
|
74
|
+
deployment: Deployment;
|
|
75
|
+
}
|
|
76
|
+
export interface NewComment {
|
|
77
|
+
body: string;
|
|
78
|
+
author: Author;
|
|
79
|
+
}
|
|
80
|
+
export interface StatusChange {
|
|
81
|
+
status: ThreadStatus;
|
|
82
|
+
by: Author;
|
|
83
|
+
}
|
|
84
|
+
/** The answer to a list request. */
|
|
85
|
+
export interface ThreadList {
|
|
86
|
+
threads: Thread[];
|
|
87
|
+
deployment: Deployment;
|
|
88
|
+
}
|
|
89
|
+
/**
|
|
90
|
+
* Which threads to list. With `page`, a page's threads are the ones with its key, and those left on its
|
|
91
|
+
* path before it had one; with only `path`, the ones on that path. Neither: every page's.
|
|
92
|
+
*/
|
|
93
|
+
export interface ThreadFilter {
|
|
94
|
+
path?: string;
|
|
95
|
+
page?: string;
|
|
96
|
+
status?: ThreadStatus;
|
|
97
|
+
}
|
|
98
|
+
/** Where comments are kept. `postgresStore` for projects, `memoryStore` for tests and trying it out. */
|
|
99
|
+
export interface CommentsStore {
|
|
100
|
+
/** Threads with their comments, newest first. */
|
|
101
|
+
list(filter?: ThreadFilter): Promise<Thread[]>;
|
|
102
|
+
/** A page with a key is now at `path`: its threads follow it. Resolves to how many moved. */
|
|
103
|
+
movePage(pageKey: string, path: string): Promise<number>;
|
|
104
|
+
get(id: string): Promise<Thread | null>;
|
|
105
|
+
createThread(input: CreateThread): Promise<Thread>;
|
|
106
|
+
/** `null` when there's no such thread. */
|
|
107
|
+
addComment(threadId: string, input: NewComment): Promise<Comment | null>;
|
|
108
|
+
/** `null` when there's no such thread. */
|
|
109
|
+
setStatus(threadId: string, status: ThreadStatus, by: string): Promise<Thread | null>;
|
|
110
|
+
/** Let go of any connection. */
|
|
111
|
+
close?(): Promise<void>;
|
|
112
|
+
}
|
package/dist/types.js
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Checking what the browser sends. Anyone who can open a preview can post, so nothing is trusted:
|
|
3
|
+
* every field is typed, trimmed and held to a length, and text is kept as text.
|
|
4
|
+
*/
|
|
5
|
+
import type { Anchor, Author, NewComment, NewThread, StatusChange } from "./types.js";
|
|
6
|
+
export declare const LIMITS: {
|
|
7
|
+
readonly body: 4000;
|
|
8
|
+
readonly name: 80;
|
|
9
|
+
readonly authorId: 64;
|
|
10
|
+
readonly path: 2048;
|
|
11
|
+
readonly locale: 35;
|
|
12
|
+
readonly kind: 40;
|
|
13
|
+
readonly key: 500;
|
|
14
|
+
readonly pageKey: 500;
|
|
15
|
+
readonly label: 200;
|
|
16
|
+
readonly field: 100;
|
|
17
|
+
readonly selector: 2000;
|
|
18
|
+
};
|
|
19
|
+
export type Checked<T> = {
|
|
20
|
+
ok: true;
|
|
21
|
+
value: T;
|
|
22
|
+
} | {
|
|
23
|
+
ok: false;
|
|
24
|
+
error: string;
|
|
25
|
+
};
|
|
26
|
+
export declare const clean: (s: string) => string;
|
|
27
|
+
export declare function checkAuthor(x: unknown): Checked<Author>;
|
|
28
|
+
export declare function checkAnchor(x: unknown): Checked<Anchor>;
|
|
29
|
+
export declare function checkBody(x: unknown): Checked<string>;
|
|
30
|
+
export declare function checkPath(x: unknown): Checked<string>;
|
|
31
|
+
export declare function checkPageKey(x: unknown): Checked<string>;
|
|
32
|
+
/** A page with a key, at the path it's at now. */
|
|
33
|
+
export declare function checkPageMove(x: unknown): Checked<{
|
|
34
|
+
pageKey: string;
|
|
35
|
+
path: string;
|
|
36
|
+
}>;
|
|
37
|
+
export declare function checkNewThread(x: unknown): Checked<NewThread>;
|
|
38
|
+
export declare function checkNewComment(x: unknown): Checked<NewComment>;
|
|
39
|
+
export declare function checkStatusChange(x: unknown): Checked<StatusChange>;
|
|
40
|
+
export declare const isId: (x: string) => boolean;
|
package/dist/validate.js
ADDED
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
export const LIMITS = {
|
|
2
|
+
body: 4000,
|
|
3
|
+
name: 80,
|
|
4
|
+
authorId: 64,
|
|
5
|
+
path: 2048,
|
|
6
|
+
locale: 35,
|
|
7
|
+
kind: 40,
|
|
8
|
+
key: 500,
|
|
9
|
+
pageKey: 500,
|
|
10
|
+
label: 200,
|
|
11
|
+
field: 100,
|
|
12
|
+
selector: 2000,
|
|
13
|
+
};
|
|
14
|
+
const fail = (error) => ({ ok: false, error });
|
|
15
|
+
const isObject = (x) => typeof x === "object" && x !== null && !Array.isArray(x);
|
|
16
|
+
/** Postgres refuses NUL in text, and nothing a person types needs it, or the other control characters bar tab and newlines. */
|
|
17
|
+
// biome-ignore lint/suspicious/noControlCharactersInRegex: removing them is the point
|
|
18
|
+
const CONTROL = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g;
|
|
19
|
+
export const clean = (s) => s.replace(CONTROL, "").replace(/\r\n?/g, "\n");
|
|
20
|
+
function text(x, name, max, { required = true, trim = true } = {}) {
|
|
21
|
+
if (typeof x !== "string")
|
|
22
|
+
return required ? fail(`${name} is missing`) : { ok: true, value: "" };
|
|
23
|
+
const value = trim ? clean(x).trim() : clean(x);
|
|
24
|
+
if (required && !value)
|
|
25
|
+
return fail(`${name} is empty`);
|
|
26
|
+
if (value.length > max)
|
|
27
|
+
return fail(`${name} is longer than ${max} characters`);
|
|
28
|
+
return { ok: true, value };
|
|
29
|
+
}
|
|
30
|
+
export function checkAuthor(x) {
|
|
31
|
+
if (!isObject(x))
|
|
32
|
+
return fail("author is missing");
|
|
33
|
+
const name = text(x.name, "author.name", LIMITS.name);
|
|
34
|
+
if (!name.ok)
|
|
35
|
+
return name;
|
|
36
|
+
const id = text(x.id, "author.id", LIMITS.authorId);
|
|
37
|
+
if (!id.ok)
|
|
38
|
+
return id;
|
|
39
|
+
return { ok: true, value: { name: name.value, id: id.value } };
|
|
40
|
+
}
|
|
41
|
+
export function checkAnchor(x) {
|
|
42
|
+
if (!isObject(x))
|
|
43
|
+
return fail("anchor is missing");
|
|
44
|
+
const kind = text(x.kind, "anchor.kind", LIMITS.kind);
|
|
45
|
+
if (!kind.ok)
|
|
46
|
+
return kind;
|
|
47
|
+
const key = text(x.key, "anchor.key", LIMITS.key, { required: false });
|
|
48
|
+
if (!key.ok)
|
|
49
|
+
return key;
|
|
50
|
+
const label = text(x.label, "anchor.label", LIMITS.label);
|
|
51
|
+
if (!label.ok)
|
|
52
|
+
return label;
|
|
53
|
+
const field = text(x.field, "anchor.field", LIMITS.field, { required: false });
|
|
54
|
+
if (!field.ok)
|
|
55
|
+
return field;
|
|
56
|
+
const selector = text(x.selector, "anchor.selector", LIMITS.selector, { required: false });
|
|
57
|
+
if (!selector.ok)
|
|
58
|
+
return selector;
|
|
59
|
+
if (!key.value && !selector.value)
|
|
60
|
+
return fail("anchor needs a key or a selector");
|
|
61
|
+
const anchor = { kind: kind.value, key: key.value, label: label.value, selector: selector.value };
|
|
62
|
+
if (field.value)
|
|
63
|
+
anchor.field = field.value;
|
|
64
|
+
return { ok: true, value: anchor };
|
|
65
|
+
}
|
|
66
|
+
export function checkBody(x) {
|
|
67
|
+
// kept as typed, apart from the ends
|
|
68
|
+
return text(x, "body", LIMITS.body);
|
|
69
|
+
}
|
|
70
|
+
export function checkPath(x) {
|
|
71
|
+
const path = text(x, "path", LIMITS.path);
|
|
72
|
+
if (!path.ok)
|
|
73
|
+
return path;
|
|
74
|
+
if (!path.value.startsWith("/") || path.value.startsWith("//"))
|
|
75
|
+
return fail("path must start with a single /");
|
|
76
|
+
return path;
|
|
77
|
+
}
|
|
78
|
+
export function checkPageKey(x) {
|
|
79
|
+
return text(x, "pageKey", LIMITS.pageKey);
|
|
80
|
+
}
|
|
81
|
+
/** A page with a key, at the path it's at now. */
|
|
82
|
+
export function checkPageMove(x) {
|
|
83
|
+
if (!isObject(x))
|
|
84
|
+
return fail("expected a JSON object");
|
|
85
|
+
const pageKey = checkPageKey(x.pageKey);
|
|
86
|
+
if (!pageKey.ok)
|
|
87
|
+
return pageKey;
|
|
88
|
+
const path = checkPath(x.path);
|
|
89
|
+
if (!path.ok)
|
|
90
|
+
return path;
|
|
91
|
+
return { ok: true, value: { pageKey: pageKey.value, path: path.value } };
|
|
92
|
+
}
|
|
93
|
+
export function checkNewThread(x) {
|
|
94
|
+
if (!isObject(x))
|
|
95
|
+
return fail("expected a JSON object");
|
|
96
|
+
const path = checkPath(x.path);
|
|
97
|
+
if (!path.ok)
|
|
98
|
+
return path;
|
|
99
|
+
const pageKey = text(x.pageKey ?? undefined, "pageKey", LIMITS.pageKey, { required: false });
|
|
100
|
+
if (!pageKey.ok)
|
|
101
|
+
return pageKey;
|
|
102
|
+
const locale = text(x.locale, "locale", LIMITS.locale, { required: false });
|
|
103
|
+
if (!locale.ok)
|
|
104
|
+
return locale;
|
|
105
|
+
const anchor = checkAnchor(x.anchor);
|
|
106
|
+
if (!anchor.ok)
|
|
107
|
+
return anchor;
|
|
108
|
+
const body = checkBody(x.body);
|
|
109
|
+
if (!body.ok)
|
|
110
|
+
return body;
|
|
111
|
+
const author = checkAuthor(x.author);
|
|
112
|
+
if (!author.ok)
|
|
113
|
+
return author;
|
|
114
|
+
let viewportWidth = null;
|
|
115
|
+
if (x.viewportWidth != null) {
|
|
116
|
+
if (typeof x.viewportWidth !== "number" || !Number.isFinite(x.viewportWidth) || x.viewportWidth < 0 || x.viewportWidth > 100_000)
|
|
117
|
+
return fail("viewportWidth must be a width in px");
|
|
118
|
+
viewportWidth = Math.round(x.viewportWidth);
|
|
119
|
+
}
|
|
120
|
+
return { ok: true, value: { path: path.value, pageKey: pageKey.value || null, locale: locale.value || null, anchor: anchor.value, viewportWidth, body: body.value, author: author.value } };
|
|
121
|
+
}
|
|
122
|
+
export function checkNewComment(x) {
|
|
123
|
+
if (!isObject(x))
|
|
124
|
+
return fail("expected a JSON object");
|
|
125
|
+
const body = checkBody(x.body);
|
|
126
|
+
if (!body.ok)
|
|
127
|
+
return body;
|
|
128
|
+
const author = checkAuthor(x.author);
|
|
129
|
+
if (!author.ok)
|
|
130
|
+
return author;
|
|
131
|
+
return { ok: true, value: { body: body.value, author: author.value } };
|
|
132
|
+
}
|
|
133
|
+
export function checkStatusChange(x) {
|
|
134
|
+
if (!isObject(x))
|
|
135
|
+
return fail("expected a JSON object");
|
|
136
|
+
if (x.status !== "open" && x.status !== "resolved")
|
|
137
|
+
return fail('status must be "open" or "resolved"');
|
|
138
|
+
const by = checkAuthor(x.by);
|
|
139
|
+
if (!by.ok)
|
|
140
|
+
return by;
|
|
141
|
+
return { ok: true, value: { status: x.status, by: by.value } };
|
|
142
|
+
}
|
|
143
|
+
const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
|
|
144
|
+
export const isId = (x) => UUID.test(x);
|
package/package.json
CHANGED
|
@@ -1,6 +1,83 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@designtools/comments",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Comments on prototypes, pinned to the module or element they're about, with no account: chosen by mouse or keyboard, stored in the project's own Postgres, worked through from the terminal.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"author": "Made by Many",
|
|
8
|
+
"repository": {
|
|
9
|
+
"type": "git",
|
|
10
|
+
"url": "git+https://github.com/madebymany/designtools.git",
|
|
11
|
+
"directory": "packages/comments"
|
|
12
|
+
},
|
|
13
|
+
"homepage": "https://github.com/madebymany/designtools/tree/main/packages/comments#readme",
|
|
14
|
+
"bugs": "https://github.com/madebymany/designtools/issues",
|
|
15
|
+
"engines": {
|
|
16
|
+
"node": ">=20"
|
|
17
|
+
},
|
|
18
|
+
"exports": {
|
|
19
|
+
".": {
|
|
20
|
+
"types": "./dist/index.d.ts",
|
|
21
|
+
"default": "./dist/index.js"
|
|
22
|
+
},
|
|
23
|
+
"./server": {
|
|
24
|
+
"types": "./dist/server/index.d.ts",
|
|
25
|
+
"default": "./dist/server/index.js"
|
|
26
|
+
},
|
|
27
|
+
"./package.json": "./package.json"
|
|
28
|
+
},
|
|
29
|
+
"bin": {
|
|
30
|
+
"designtools-comments": "dist/cli.js"
|
|
31
|
+
},
|
|
32
|
+
"files": [
|
|
33
|
+
"dist",
|
|
34
|
+
"README.md",
|
|
35
|
+
"CHANGELOG.md",
|
|
36
|
+
"LICENSE"
|
|
37
|
+
],
|
|
38
|
+
"sideEffects": false,
|
|
39
|
+
"keywords": [
|
|
40
|
+
"comments",
|
|
41
|
+
"feedback",
|
|
42
|
+
"review",
|
|
43
|
+
"prototype",
|
|
44
|
+
"design-tools",
|
|
45
|
+
"accessibility",
|
|
46
|
+
"nextjs",
|
|
47
|
+
"postgres"
|
|
48
|
+
],
|
|
49
|
+
"peerDependencies": {
|
|
50
|
+
"@base-ui/react": "^1.6.0",
|
|
51
|
+
"lucide-react": "^1.23.0",
|
|
52
|
+
"react": ">=19",
|
|
53
|
+
"react-dom": ">=19"
|
|
54
|
+
},
|
|
55
|
+
"dependencies": {
|
|
56
|
+
"postgres": "^3.4.9",
|
|
57
|
+
"@designtools/widgets": "0.2.0"
|
|
58
|
+
},
|
|
59
|
+
"devDependencies": {
|
|
60
|
+
"@base-ui/react": "1.6.0",
|
|
61
|
+
"@electric-sql/pglite": "^0.5.16",
|
|
62
|
+
"@tailwindcss/postcss": "4.3.3",
|
|
63
|
+
"@types/node": "^24.19.1",
|
|
64
|
+
"@types/react": "^19.3.0",
|
|
65
|
+
"@types/react-dom": "^19.3.0",
|
|
66
|
+
"happy-dom": "^20.14.6",
|
|
67
|
+
"lucide-react": "1.23.0",
|
|
68
|
+
"postcss": "8.5.29",
|
|
69
|
+
"react": "19.2.7",
|
|
70
|
+
"react-dom": "19.2.7",
|
|
71
|
+
"tailwindcss": "4.3.3",
|
|
72
|
+
"tsx": "4.23.15",
|
|
73
|
+
"typescript": "~6.0.3",
|
|
74
|
+
"vitest": "^4.1.11"
|
|
75
|
+
},
|
|
76
|
+
"scripts": {
|
|
77
|
+
"build": "rm -rf dist && tsc -p tsconfig.build.json && node scripts/fix-extensions.mjs && node ../widgets/scripts/build-css.mjs src/styles.css dist/css.js && chmod +x dist/cli.js",
|
|
78
|
+
"typecheck": "tsc --noEmit",
|
|
79
|
+
"test": "vitest run",
|
|
80
|
+
"cli": "tsx src/cli.ts",
|
|
81
|
+
"e2e": "node e2e/check.mjs"
|
|
82
|
+
}
|
|
6
83
|
}
|