@vinena/knobs 0.5.2 → 0.6.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 +39 -0
- package/README.md +7 -6
- package/dist/context-amfyasb5.js +23 -0
- package/dist/context-svtr7vwt.js +22 -0
- package/dist/early.global.js +6 -6
- package/dist/edit/css.d.ts +59 -0
- package/dist/edit/html.d.ts +91 -0
- package/dist/edit/keep.d.ts +175 -0
- package/dist/edit/log.d.ts +107 -0
- package/dist/edit/replay.d.ts +28 -0
- package/dist/edit/risk.d.ts +33 -0
- package/dist/edit/rule.d.ts +31 -0
- package/dist/edit/source.d.ts +12 -0
- package/dist/edit/text.d.ts +66 -0
- package/dist/elementsview-fyc06wjt.js +3702 -0
- package/dist/elementsview-k6zvvcne.js +3701 -0
- package/dist/engine/browserdraw.d.ts +5 -0
- package/dist/engine/browserkit.d.ts +2 -0
- package/dist/engine/devices.d.ts +3 -2
- package/dist/engine/dock.d.ts +3 -4
- package/dist/engine/frame.d.ts +1 -1
- package/dist/engine/frames.d.ts +1 -0
- package/dist/engine/identity.d.ts +5 -1
- package/dist/engine/index.d.ts +2 -0
- package/dist/engine/mock.d.ts +0 -2
- package/dist/engine/mockdata.d.ts +4 -3
- package/dist/engine/mockdraw.d.ts +2 -14
- package/dist/engine/morphrun.d.ts +4 -0
- package/dist/engine/native.d.ts +31 -3
- package/dist/engine/notice.d.ts +1 -2
- package/dist/engine/style.d.ts +15 -0
- package/dist/engine/width.d.ts +3 -0
- package/dist/{framekit-w0v516w5.js → framekit-622h6w1f.js} +264 -105
- package/dist/{framekit-te90cjs0.js → framekit-yx612r28.js} +264 -105
- package/dist/index-0zp9py56.js +859 -0
- package/dist/{index-9re7sv56.js → index-1mstjadm.js} +126 -2167
- package/dist/{index-30fc6php.js → index-4a4x1bt2.js} +1 -1
- package/dist/index-58jdczmj.js +44 -0
- package/dist/index-5tv6sr74.js +23 -0
- package/dist/index-6bc2ztfd.js +688 -0
- package/dist/index-7cb4x1vj.js +1885 -0
- package/dist/index-a974q3aa.js +34 -0
- package/dist/{index-r72tz2vn.js → index-aymfvd8s.js} +1 -1
- package/dist/{index-trx7bxdk.js → index-aynkv7qk.js} +11 -8
- package/dist/{index-xjhwp5cj.js → index-dzm8ywq0.js} +504 -2362
- package/dist/{index-dan2kpsd.js → index-f60yax1j.js} +13 -8
- package/dist/index-f67wctn3.js +1858 -0
- package/dist/{index-agwr37gw.js → index-ftjdt358.js} +8 -171
- package/dist/{index-pewcdh28.js → index-gm51cthv.js} +2 -45
- package/dist/index-kfdzsyyw.js +1859 -0
- package/dist/index-t4kssacm.js +208 -0
- package/dist/index-v0ht9q0g.js +1518 -0
- package/dist/{index-sxe5079a.js → index-x59vz1xx.js} +262 -901
- package/dist/index-xh39jtkq.js +32 -0
- package/dist/index-yb7fc59g.js +718 -0
- package/dist/index-zd6adby9.js +496 -0
- package/dist/index.d.ts +62 -0
- package/dist/index.global.js +447 -160
- package/dist/index.js +533 -485
- package/dist/react-0wepdf60.js +1519 -0
- package/dist/{react-4pvp6amm.js → react-1gqwa2yw.js} +1 -1
- package/dist/{index-hv02xka3.js → react-3mfz1x2a.js} +126 -2167
- package/dist/react-4rbjw9af.js +33 -0
- package/dist/react-5rq7bnsy.js +210 -0
- package/dist/react-6bz05qk1.js +860 -0
- package/dist/{react-05jh9jv5.js → react-6fnxxs30.js} +8 -171
- package/dist/react-6q2cw2ya.js +689 -0
- package/dist/{react-sw8d8c94.js → react-6t4dbdzn.js} +11 -8
- package/dist/react-88es9b5q.js +719 -0
- package/dist/react-97b5b8j4.js +46 -0
- package/dist/{react-16spgn0h.js → react-bxzn8vq5.js} +1 -1
- package/dist/{react-ayg1bgw3.js → react-cs62p9qh.js} +83 -722
- package/dist/react-ethftdxp.js +497 -0
- package/dist/react-fp73vhyd.js +36 -0
- package/dist/{react-exjcpxma.js → react-me102s1a.js} +2 -45
- package/dist/react-t2qnewz2.js +24 -0
- package/dist/react-ttj8f9qp.js +1886 -0
- package/dist/{react-zy1mmhgz.js → react-v8497a41.js} +13 -8
- package/dist/{react-fm9y8dbn.js → react-wqn4sx0n.js} +276 -2133
- package/dist/react.js +529 -485
- package/dist/replay-j18rw92k.js +258 -0
- package/dist/replay-vtg0vqj2.js +257 -0
- package/dist/{storageview-s7heg93p.js → storageview-6xj7zb63.js} +11 -7
- package/dist/{storageview-r595qpt9.js → storageview-pzn8yaad.js} +11 -7
- package/dist/styles/force.d.ts +66 -0
- package/dist/types.d.ts +7 -0
- package/dist/ui/bindings.d.ts +31 -5
- package/dist/ui/changes.d.ts +49 -0
- package/dist/ui/cssauto.d.ts +119 -0
- package/dist/ui/cssedit.d.ts +80 -0
- package/dist/ui/domedit.d.ts +99 -0
- package/dist/ui/domtree.d.ts +26 -1
- package/dist/ui/elementsview.d.ts +19 -2
- package/dist/ui/htmledit.d.ts +62 -0
- package/dist/ui/inspector.d.ts +6 -1
- package/dist/ui/keys.d.ts +12 -8
- package/dist/ui/pane.d.ts +0 -2
- package/dist/ui/panel.d.ts +3 -0
- package/dist/ui/prefs.d.ts +30 -10
- package/dist/ui/settings.d.ts +10 -0
- package/dist/ui/size.d.ts +14 -22
- package/dist/ui/stylesview.d.ts +30 -1
- package/package.json +1 -1
- package/skills/devknobs/SKILL.md +95 -0
- package/dist/elementsview-2z4pkrdz.js +0 -2873
- package/dist/elementsview-qn8qyksa.js +0 -2874
- package/dist/index-78r0f8pw.js +0 -27
- package/dist/react-adky72h9.js +0 -29
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Edits of the page's html, made in the DOM tree: a text changed, an
|
|
3
|
+
* attribute set, added or taken out, an element written anew as html, an
|
|
4
|
+
* element hidden, a node deleted. Each keeps the very nodes it moved, so
|
|
5
|
+
* undo puts back what the page had. An edit goes on and comes off only where
|
|
6
|
+
* its node is as the edit left it: where the page's own script changed or
|
|
7
|
+
* replaced the node since, as a framework does when it renders again, the
|
|
8
|
+
* edit stays as text, and undo only takes it out of the log. To use it:
|
|
9
|
+
*
|
|
10
|
+
* const change = textEdit(target, node, "Buy now");
|
|
11
|
+
* if (change) edits.record(change);
|
|
12
|
+
*/
|
|
13
|
+
import type { Change, EditKind, EditPlace, EditTarget } from "./log";
|
|
14
|
+
/** The html edits, by their kind. */
|
|
15
|
+
export type HtmlKind = Extract<EditKind, "text" | "attr" | "html" | "hide" | "delete" | "move">;
|
|
16
|
+
/** The attribute a hidden element carries. devknobs' own, so the tree and a copy leave it out. */
|
|
17
|
+
export declare const HIDE_ATTRIBUTE = "data-devknobs-hide";
|
|
18
|
+
/** What hides an element and all in it, as the browsers' tools hide one: its box keeps its place. */
|
|
19
|
+
export declare const HIDE_CSS = "[data-devknobs-hide], [data-devknobs-hide] * { visibility: hidden !important; }";
|
|
20
|
+
/** The node that stands where `node` stood, after edits put others in its place. Null where none does. */
|
|
21
|
+
export declare function successor(node: Node): Node | null;
|
|
22
|
+
/**
|
|
23
|
+
* A text node's text changed to `text`, the white space around it kept.
|
|
24
|
+
* `property` says which of its element's texts it is. Null where nothing
|
|
25
|
+
* would change, or where the text would be empty: a delete takes a text out.
|
|
26
|
+
*/
|
|
27
|
+
export declare function textEdit(target: EditTarget, node: Node, text: string, property?: string): Change | null;
|
|
28
|
+
/** An attribute's name as the element keeps it: lower case on an html element. */
|
|
29
|
+
export declare function attributeName(element: Element, name: string): string;
|
|
30
|
+
/** An attribute set to `value`, added, or with null taken out. Null where nothing would change, or for one of devknobs'. */
|
|
31
|
+
export declare function attrEdit(target: EditTarget, element: Element, name: string, value: string | null): Change | null;
|
|
32
|
+
/** The nodes `html` makes, parsed in the element's document as the page's own html would be, scripts left inert. */
|
|
33
|
+
export declare function parseHtml(doc: Document, html: string): Node[];
|
|
34
|
+
/** Nodes as markup, as the browser writes them back: an element's outer html, a comment, a text with `&`, `<` and `>` escaped. */
|
|
35
|
+
export declare function markupOfNodes(nodes: readonly Node[]): string;
|
|
36
|
+
/** Whether nodes carry devknobs' own attribute, on them or anything in them, which no edit makes. */
|
|
37
|
+
export declare function holdsReserved(nodes: readonly Node[]): boolean;
|
|
38
|
+
/**
|
|
39
|
+
* An element written anew: `nodes` in its place. `before` is its markup as
|
|
40
|
+
* the tree copies it, and the edit's `after` the nodes' markup as the
|
|
41
|
+
* browser writes it back, so two edits of one element compare alike. Null
|
|
42
|
+
* where the nodes hold no element, carry devknobs' own attribute, or come to
|
|
43
|
+
* the markup it has. It goes on and comes off only where the element, or the
|
|
44
|
+
* nodes in its place, still stand in the parent it had, in one run.
|
|
45
|
+
*/
|
|
46
|
+
export declare function htmlEdit(target: EditTarget, element: Element, before: string, nodes: readonly Node[]): Change | null;
|
|
47
|
+
/** Bring the rule that hides into the element's document or shadow root, once. */
|
|
48
|
+
export declare function hideStyle(element: Element): void;
|
|
49
|
+
/** An element hidden, or shown again where a hide is on it. `style` brings in the rule that hides. */
|
|
50
|
+
export declare function hideEdit(target: EditTarget, element: Element, style?: (element: Element) => void): Change;
|
|
51
|
+
/**
|
|
52
|
+
* A node deleted: `before` is its markup, `property` what it is in its
|
|
53
|
+
* element. Undo puts it back where it stood, before the node that came after
|
|
54
|
+
* it, or after the one before where that went, or first where it was first.
|
|
55
|
+
* Null for a node with no parent.
|
|
56
|
+
*/
|
|
57
|
+
export declare function deleteEdit(target: EditTarget, node: Node, before: string, property?: string): Change | null;
|
|
58
|
+
/** The element after a node among its parent's, devknobs' own left out. Null at the end. */
|
|
59
|
+
export declare function nextElementOf(node: Node): Element | null;
|
|
60
|
+
/** The element before a node among its parent's, devknobs' own left out. Null at the start. */
|
|
61
|
+
export declare function previousElementOf(node: Node): Element | null;
|
|
62
|
+
/** The first element in a node, devknobs' own left out. */
|
|
63
|
+
export declare function firstElementOf(node: Node): Element | null;
|
|
64
|
+
/**
|
|
65
|
+
* Whether an element can be moved: one in an element, and not the head or
|
|
66
|
+
* body, devknobs' own, one that holds devknobs' own nodes, as the body holds
|
|
67
|
+
* the panel, nor a script, frame or the like, or one that holds one. The
|
|
68
|
+
* root element has a document above it, and stays.
|
|
69
|
+
*/
|
|
70
|
+
export declare function movable(node: Node): node is Element;
|
|
71
|
+
/** Whether an element can take `element` moved into it: on the page, not devknobs' own, not the element or one in it, through shadow roots too, and not one of `EMPTY`. */
|
|
72
|
+
export declare function canHold(parent: Node, element: Element): parent is Element;
|
|
73
|
+
/** An element as a move says it: its tag, with its id and class where it has them. */
|
|
74
|
+
export declare function tagLabel(element: Element): string;
|
|
75
|
+
/** A place in words: `before <li class="x"> in <ul>`, `before the 2nd <li> in <ul>`, or `at the end of <ul>`. */
|
|
76
|
+
export declare function placeWords(parent: Element, next: Element | null): string;
|
|
77
|
+
/**
|
|
78
|
+
* An element moved into `to.parent`, before `to.next`, or at its end with
|
|
79
|
+
* null. `places` are the two places as selectors, read before the move. Null
|
|
80
|
+
* where it cannot move, where the place cannot take it, or where it already
|
|
81
|
+
* stands there. It goes on only where the element still stands where it was,
|
|
82
|
+
* and comes off only where it still stands where it went: undo puts it back
|
|
83
|
+
* before the node that came after it, or after the one before.
|
|
84
|
+
*/
|
|
85
|
+
export declare function moveEdit(target: EditTarget, element: Element, to: {
|
|
86
|
+
parent: Element;
|
|
87
|
+
next: Element | null;
|
|
88
|
+
}, places: {
|
|
89
|
+
from: EditPlace;
|
|
90
|
+
to: EditPlace;
|
|
91
|
+
}): Change | null;
|
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Edits kept after a reload. With the Elements view's switch on, the edits
|
|
3
|
+
* in force are kept for the page, its address without the query, as plain
|
|
4
|
+
* json: each one's kind, target, property and values, no node of the page.
|
|
5
|
+
* As the page loads again and settles, the kept edits are made again in
|
|
6
|
+
* order, each only where the page still has its target and the value before
|
|
7
|
+
* it, through the same log as the panel's, so undo and the changes list take
|
|
8
|
+
* them as any other. An html or attribute edit, which could change what a
|
|
9
|
+
* script of the page does, is never made as the page loads: it and all after
|
|
10
|
+
* it wait for the user's click on `apply`, as a page script may have planted
|
|
11
|
+
* them. Turning the switch off forgets them. Forced states are no edits, and
|
|
12
|
+
* are never kept, nor one that could run a script (`risk.ts`). While the page
|
|
13
|
+
* shows in devknobs' frame, for a pinned panel or a device, the edits made in
|
|
14
|
+
* it are the page's, kept while the frame shows the page they are kept for,
|
|
15
|
+
* and made again in it; those of any other window are not kept.
|
|
16
|
+
*
|
|
17
|
+
* Without the extension they are in the page's `localStorage`, one item per
|
|
18
|
+
* page (`EDITS_KEY` and the path), none in fresh mode; the extension keeps
|
|
19
|
+
* them in its own storage through an `EditsStore`. To use it:
|
|
20
|
+
*
|
|
21
|
+
* const keep = startKeep(); // at mount: replays what the page kept
|
|
22
|
+
* keep.set(true); keep.on(); // the switch
|
|
23
|
+
* stopKeep(); // at unmount, before the edits are undone
|
|
24
|
+
*/
|
|
25
|
+
import { type Edit, type EditLog } from "./log";
|
|
26
|
+
/** An edit as kept and as `setEdits` takes it: an `edits()` entry, its id left out. */
|
|
27
|
+
export type SavedEdit = Omit<Edit, "id">;
|
|
28
|
+
/** What is kept for a page: its edits, oldest first, with their version. */
|
|
29
|
+
export interface KeptEdits {
|
|
30
|
+
v: number;
|
|
31
|
+
edits: SavedEdit[];
|
|
32
|
+
}
|
|
33
|
+
/** An edit that was not made again, and why. */
|
|
34
|
+
export interface Skipped {
|
|
35
|
+
edit: unknown;
|
|
36
|
+
reason: string;
|
|
37
|
+
}
|
|
38
|
+
/** What making a list of edits again came to. */
|
|
39
|
+
export interface Replayed {
|
|
40
|
+
applied: Edit[];
|
|
41
|
+
skipped: Skipped[];
|
|
42
|
+
}
|
|
43
|
+
/** Where the edits of a page are kept in `localStorage`, its path after it. */
|
|
44
|
+
export declare const EDITS_KEY = "devknobs:edits:";
|
|
45
|
+
/** The version `EDITS_KEY` keeps. Bump it with a new shape, see stored.ts. */
|
|
46
|
+
export declare const EDITS_VERSION = 1;
|
|
47
|
+
/** The most edits kept for a page: the first ones, as a later edit goes on from those before. */
|
|
48
|
+
export declare const MAX_EDITS = 200;
|
|
49
|
+
/** The most a page's kept edits take, as json, in characters. */
|
|
50
|
+
export declare const MAX_BYTES: number;
|
|
51
|
+
/** The most pages edits are kept for: the page kept longest ago goes first. */
|
|
52
|
+
export declare const MAX_PAGES = 20;
|
|
53
|
+
/** Why an edit was not made again. */
|
|
54
|
+
export declare const REASONS: {
|
|
55
|
+
readonly invalid: "not an edit devknobs reads";
|
|
56
|
+
readonly missing: "not found on the page";
|
|
57
|
+
readonly rule: "its rule is not on the page";
|
|
58
|
+
readonly changed: "the page has another value now";
|
|
59
|
+
readonly refused: "the page did not take it";
|
|
60
|
+
};
|
|
61
|
+
/** One edit in `edits()`'s shape, read field by field, or null where it is not one. Its id, where it has one, is left out. */
|
|
62
|
+
export declare function readSavedEdit(value: unknown): SavedEdit | null;
|
|
63
|
+
/**
|
|
64
|
+
* What a page keeps, or null where it keeps nothing devknobs reads: no
|
|
65
|
+
* object, a newer version, too many edits, one that is none, or one that
|
|
66
|
+
* could run a script, which devknobs never keeps, so a script planted it.
|
|
67
|
+
*/
|
|
68
|
+
export declare function readKept(value: unknown): KeptEdits | null;
|
|
69
|
+
/**
|
|
70
|
+
* Edits as kept: the first that fit in `MAX_EDITS` and `MAX_BYTES`, as the
|
|
71
|
+
* list's json counts them, up to the first that `readSavedEdit` would not
|
|
72
|
+
* read back or that could run a script, and how many more there were. A
|
|
73
|
+
* later edit goes on from those before it, so none past that point is kept.
|
|
74
|
+
*/
|
|
75
|
+
export declare function toKept(list: readonly Edit[]): {
|
|
76
|
+
kept: KeptEdits;
|
|
77
|
+
cut: number;
|
|
78
|
+
};
|
|
79
|
+
/**
|
|
80
|
+
* @internal Where a mount keeps the edits of the page in place of
|
|
81
|
+
* `localStorage`, for the devknobs extension. `load` gives what is kept for
|
|
82
|
+
* this page, read as `readKept` reads it, null for nothing, and undefined
|
|
83
|
+
* until it is known. `save` keeps the edits for this page, or with null
|
|
84
|
+
* forgets them. `subscribe` hears what is kept change and returns the way to stop.
|
|
85
|
+
*/
|
|
86
|
+
export interface EditsStore {
|
|
87
|
+
load(): unknown;
|
|
88
|
+
save(kept: KeptEdits | null): void;
|
|
89
|
+
subscribe(listener: () => void): () => void;
|
|
90
|
+
}
|
|
91
|
+
/** The page's path now, `/` where it has none to read. */
|
|
92
|
+
export declare function pathNow(): string;
|
|
93
|
+
/**
|
|
94
|
+
* The page's own `localStorage`, an item per path. The path is the one the
|
|
95
|
+
* page loaded at, read once, so a move of the app's router to another path
|
|
96
|
+
* keeps and forgets the edits of the page they were made on. In fresh mode
|
|
97
|
+
* nothing is read or written.
|
|
98
|
+
*/
|
|
99
|
+
export declare function localEditsStore(path?: string): EditsStore;
|
|
100
|
+
/** What making kept edits again came to, with those that wait for the user. */
|
|
101
|
+
export interface Replaying extends Replayed {
|
|
102
|
+
/** The edits from the first one that waits for the user's click on: an html or attribute edit. */
|
|
103
|
+
waiting: SavedEdit[];
|
|
104
|
+
}
|
|
105
|
+
/** Makes kept edits again on `doc`, through the log. With `hold`, an html or attribute edit and all after it wait. */
|
|
106
|
+
export type Replay = (log: EditLog, list: readonly unknown[], hold: boolean, doc: Document) => Replaying;
|
|
107
|
+
/** What the replay on load came to: how many edits were made again, and those that were not. */
|
|
108
|
+
export interface Restored {
|
|
109
|
+
kept: number;
|
|
110
|
+
missed: Skipped[];
|
|
111
|
+
}
|
|
112
|
+
export interface Keeper {
|
|
113
|
+
/** Whether what the page keeps is known yet: the extension's store tells it a moment after the mount. Until then the switch does nothing. */
|
|
114
|
+
known(): boolean;
|
|
115
|
+
/** Whether the page keeps its edits: the switch. */
|
|
116
|
+
on(): boolean;
|
|
117
|
+
/** Turn the switch on, which keeps the edits in force now, or off, which forgets them, those that wait too. */
|
|
118
|
+
set(on: boolean): void;
|
|
119
|
+
/** What the replay on load came to, or null where none ran. */
|
|
120
|
+
restored(): Restored | null;
|
|
121
|
+
/**
|
|
122
|
+
* The kept edits that wait for the user: from the first html or attribute
|
|
123
|
+
* edit on, which could change what a script of the page does, so none is
|
|
124
|
+
* made as the page loads. Until they are made, nothing new is kept.
|
|
125
|
+
*/
|
|
126
|
+
waiting(): readonly SavedEdit[];
|
|
127
|
+
/** Make the edits that wait. Only for a trusted click on the panel's own button. */
|
|
128
|
+
applyWaiting(): void;
|
|
129
|
+
/** How many edits in force are kept. */
|
|
130
|
+
kept(): number;
|
|
131
|
+
/** How many edits in force are past the caps, and not kept. */
|
|
132
|
+
cut(): number;
|
|
133
|
+
/** Hear the switch, the replay or the cut change. Returns the way to stop. */
|
|
134
|
+
subscribe(listener: () => void): () => void;
|
|
135
|
+
stop(): void;
|
|
136
|
+
}
|
|
137
|
+
export interface KeeperOptions {
|
|
138
|
+
log: EditLog;
|
|
139
|
+
store: EditsStore;
|
|
140
|
+
/** The page's window: an edit made in another, as the width knob's frame, is not kept. */
|
|
141
|
+
view: Window;
|
|
142
|
+
/** Loads what makes edits again. Defaults to `replay.ts`, loaded once there is something to make. */
|
|
143
|
+
replay?: () => Promise<Replay>;
|
|
144
|
+
/** Waits for the page to be loaded and still. */
|
|
145
|
+
settled?: () => Promise<void>;
|
|
146
|
+
/** The window inside devknobs' frame while it shows this page, else null: edits made in it are kept, and made again in it. */
|
|
147
|
+
frame?: () => Window | null;
|
|
148
|
+
}
|
|
149
|
+
/** How long the page has to be still before kept edits are made again, and the longest it is waited for, in ms. */
|
|
150
|
+
export declare const QUIET = 300;
|
|
151
|
+
export declare const SETTLE_MAX = 3000;
|
|
152
|
+
/**
|
|
153
|
+
* The window inside devknobs' frame, from `inner`, while it shows the page
|
|
154
|
+
* `view` loaded at `path`: on its origin, at that path, and loaded so far.
|
|
155
|
+
* Null for no frame, for one still blank or on another page, or another origin,
|
|
156
|
+
* and while `framed` is false, as the frame is closing and takes its document with it.
|
|
157
|
+
*/
|
|
158
|
+
export declare function framedPage(view: Window, inner: Window | null, path: string, framed: boolean): Window | null;
|
|
159
|
+
/**
|
|
160
|
+
* The page settled, as `settled` says, and where it shows in devknobs'
|
|
161
|
+
* frame, as `framing` says it does, the frame's page too: up to `longest` ms
|
|
162
|
+
* for `frame` to give it, then as long as `settled` waits for it.
|
|
163
|
+
*/
|
|
164
|
+
export declare function pageSettled(view: Window, framing: () => boolean, frame: () => Window | null, longest?: number, settle?: (view: Window) => Promise<void>): Promise<void>;
|
|
165
|
+
/** The page loaded, and nothing on it changed for `quiet` ms, or `longest` ms went by: a framework has drawn it. */
|
|
166
|
+
export declare function settled(view: Window, quiet?: number, longest?: number): Promise<void>;
|
|
167
|
+
export declare function createKeeper(options: KeeperOptions): Keeper;
|
|
168
|
+
/** Start keeping the page's edits, in `store` or the page's `localStorage`, and make those it kept again, where `page` says the page shows. */
|
|
169
|
+
export declare function startKeep(store?: EditsStore, page?: Pick<KeeperOptions, "frame" | "settled">): Keeper;
|
|
170
|
+
/** Stop keeping them: what the page does to its edits from now on is not kept. */
|
|
171
|
+
export declare function stopKeep(): void;
|
|
172
|
+
/** The page's kept edits were undone: the next mount makes them again. */
|
|
173
|
+
export declare function forgetReplay(): void;
|
|
174
|
+
/** The keeper of the page, or null while devknobs is not mounted. */
|
|
175
|
+
export declare function keeper(): Keeper | null;
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The edits made on the page from the panel, in the order they were made,
|
|
3
|
+
* with undo and redo. An edit is plain data an agent can read and put in the
|
|
4
|
+
* code: what it changed, where that is written, and the value before and
|
|
5
|
+
* after. Each one is recorded with its own way to apply and revert itself on
|
|
6
|
+
* the live page, which never leaves this module. To use it:
|
|
7
|
+
*
|
|
8
|
+
* const edit = edits.record(change); // applies it, or null where it did not take
|
|
9
|
+
* edits.undo(); edits.redo(); edits.undoAll();
|
|
10
|
+
* edits.list(); // the edits in force, as plain data
|
|
11
|
+
*
|
|
12
|
+
* A new kind of edit only brings its own `Change`: the log stays the same.
|
|
13
|
+
*/
|
|
14
|
+
/**
|
|
15
|
+
* What an edit changes: a css declaration's value, a declaration turned off
|
|
16
|
+
* or on, a property added, a new rule, or in the html a text, an attribute,
|
|
17
|
+
* an element written anew as html, an element hidden, a node deleted, an
|
|
18
|
+
* element moved.
|
|
19
|
+
*/
|
|
20
|
+
export type EditKind = "css-value" | "css-toggle" | "css-add" | "css-rule" | "text" | "attr" | "html" | "hide" | "delete" | "move";
|
|
21
|
+
/** Where a moved element stands, as selectors read before the move: the element it is in, and the one it stands before, null at the end. */
|
|
22
|
+
export interface EditPlace {
|
|
23
|
+
parent: string;
|
|
24
|
+
next: string | null;
|
|
25
|
+
}
|
|
26
|
+
/** Where an edit is, for an agent to find it in the code. */
|
|
27
|
+
export interface EditTarget {
|
|
28
|
+
/** A css selector that finds the element on the page. */
|
|
29
|
+
selector: string;
|
|
30
|
+
/** Where the element is written, `file:line`, when grab's source lookup finds it. */
|
|
31
|
+
source?: string;
|
|
32
|
+
/** The rule the edit is in. Left out for an edit of the element's own `style`. */
|
|
33
|
+
rule?: {
|
|
34
|
+
selectorText: string;
|
|
35
|
+
/** The stylesheet's address, `<style>` for an inline one, `constructed` for an adopted one, `new rule` for a rule the panel added. */
|
|
36
|
+
sheet: string;
|
|
37
|
+
/** The element that brought the stylesheet in, as `style#theme`. Null for an adopted one. */
|
|
38
|
+
owner: string | null;
|
|
39
|
+
/** Tells stylesheets apart on the page, two `<style>` elements say, for as long as it is up. */
|
|
40
|
+
sheetId: number;
|
|
41
|
+
/** Its index in the stylesheet, then in each rule around it, outermost first. */
|
|
42
|
+
path: number[];
|
|
43
|
+
/** What it sits in, outermost first: `@media (min-width: 640px)`, `@layer base`, the selector of a rule it is nested in. */
|
|
44
|
+
context: string[];
|
|
45
|
+
};
|
|
46
|
+
}
|
|
47
|
+
export interface Edit {
|
|
48
|
+
id: number;
|
|
49
|
+
kind: EditKind;
|
|
50
|
+
target: EditTarget;
|
|
51
|
+
/**
|
|
52
|
+
* What in its place it changes: the css property, as written, `rule` for
|
|
53
|
+
* a new rule, whose selector is its value after, the attribute's name, `text` for the element's text (`text 2` for its second
|
|
54
|
+
* text), `html` for its markup, `hidden` for a hide, `node` for a delete and a move.
|
|
55
|
+
*/
|
|
56
|
+
property: string;
|
|
57
|
+
/** The value before, `!important` and all, or null where it was not set. For `html` and `delete`, the markup. For `move`, where it stood, in words. */
|
|
58
|
+
before: string | null;
|
|
59
|
+
/** The value after, or null where the edit took it away. For `move`, where it stands now, in words. */
|
|
60
|
+
after: string | null;
|
|
61
|
+
/** For a move: where the element stood. */
|
|
62
|
+
from?: EditPlace;
|
|
63
|
+
/** For a move: where it stands now. */
|
|
64
|
+
to?: EditPlace;
|
|
65
|
+
}
|
|
66
|
+
/** An edit and how it goes on and off the page. */
|
|
67
|
+
export interface Change {
|
|
68
|
+
edit: Omit<Edit, "id">;
|
|
69
|
+
/** Put the edit on the page. False where the page did not take it, as for a value that is no css. */
|
|
70
|
+
apply(): boolean;
|
|
71
|
+
/** Take it off again. */
|
|
72
|
+
revert(): void;
|
|
73
|
+
/**
|
|
74
|
+
* The window of the page it is on. When that page goes, as a frame
|
|
75
|
+
* reloads, the edit stays in the log as text, and lets go of the page:
|
|
76
|
+
* undoing it then only takes it out of the log.
|
|
77
|
+
*/
|
|
78
|
+
view?: Window | null;
|
|
79
|
+
}
|
|
80
|
+
/** An edit as recorded, with what it was recorded from. */
|
|
81
|
+
export interface Recorded {
|
|
82
|
+
edit: Edit;
|
|
83
|
+
change: Change;
|
|
84
|
+
/** The window the edit was made in, as it was recorded: it stays when the change lets go of its page. */
|
|
85
|
+
readonly view: Window | null;
|
|
86
|
+
}
|
|
87
|
+
export interface EditLog {
|
|
88
|
+
/** Apply a change and record it. Null where it did not take, and then nothing is recorded. */
|
|
89
|
+
record(change: Change): Edit | null;
|
|
90
|
+
/** Revert the last edit in force. Null with none. */
|
|
91
|
+
undo(): Edit | null;
|
|
92
|
+
/** Apply again the last edit undone, until a new one is recorded. Null with none, or where the page no longer takes it: that edit is dropped. */
|
|
93
|
+
redo(): Edit | null;
|
|
94
|
+
/** Revert every edit, the last first, and forget them. Says how many there were. */
|
|
95
|
+
undoAll(): number;
|
|
96
|
+
/** The edits in force, oldest first, as plain data. */
|
|
97
|
+
list(): Edit[];
|
|
98
|
+
/** The edits in force with their changes, oldest first. Not a copy: read only. */
|
|
99
|
+
recorded(): readonly Recorded[];
|
|
100
|
+
/** Fill in what was found out about an edit's target later, as its source. */
|
|
101
|
+
locate(id: number, patch: Partial<EditTarget>): void;
|
|
102
|
+
/** Hear the edits change. Returns the way to stop. */
|
|
103
|
+
subscribe(listener: () => void): () => void;
|
|
104
|
+
}
|
|
105
|
+
export declare function createEditLog(): EditLog;
|
|
106
|
+
/** The page's one log, which the panel's views, reset and `devknobs.edits()` share. */
|
|
107
|
+
export declare const edits: EditLog;
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Edits made again from their plain data, as kept for a page or handed to
|
|
3
|
+
* `devknobs.setEdits()`: each one's element found by its selector, its rule
|
|
4
|
+
* by its selector, what it sits in and its stylesheet, and its text by which
|
|
5
|
+
* of the element's texts it is. An edit is made only where the page has the
|
|
6
|
+
* value it had before it, and goes to the log as one made in the panel. A
|
|
7
|
+
* new rule is made anew, and the edits of its declarations go to the rule
|
|
8
|
+
* made, as told by the id its stylesheet had. An html or attribute edit that
|
|
9
|
+
* could run a script is never made, and after a delete, a move or an html edit
|
|
10
|
+
* that was not made, no later edit is: it may stand on it. As the page loads,
|
|
11
|
+
* `hold` leaves the first html or attribute edit and all after it waiting for
|
|
12
|
+
* the user. Loaded only once there is an edit to make. To use it:
|
|
13
|
+
*
|
|
14
|
+
* const { applied, skipped, waiting } = replayEdits(edits, list, hold);
|
|
15
|
+
*/
|
|
16
|
+
import { type Replaying } from "./keep";
|
|
17
|
+
import type { EditLog } from "./log";
|
|
18
|
+
/** Why an edit after one that was not made is not made either. */
|
|
19
|
+
export declare const AFTER_MISSED = "an earlier edit it may depend on was not made";
|
|
20
|
+
/** The element a selector grab wrote finds, through shadow roots and frames. Null where it finds none. */
|
|
21
|
+
export declare function findElement(doc: Document, selector: string): Element | null;
|
|
22
|
+
/**
|
|
23
|
+
* Make edits again, in order, through the log. Each entry is read as
|
|
24
|
+
* `edits()` writes it, and one that is not an edit is skipped. Returns the
|
|
25
|
+
* edits made, as the log has them, those skipped with the reason, and with
|
|
26
|
+
* `hold` those that wait for the user.
|
|
27
|
+
*/
|
|
28
|
+
export declare function replayEdits(log: EditLog, list: readonly unknown[], hold?: boolean, doc?: Document): Replaying;
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What in an edit could run a script on the page: an element that runs or
|
|
3
|
+
* loads one (`<script>`, a frame, an `<object>`, a `<base>`), an `on…`
|
|
4
|
+
* handler, a `srcdoc`, or a `javascript:` address, and any attribute or text
|
|
5
|
+
* of the page's own such elements, which could turn a data script into one
|
|
6
|
+
* that runs, or move where a `<base>` sends addresses. Kept edits and edits an
|
|
7
|
+
* agent hands in are made only where none of it is, so a list a page script
|
|
8
|
+
* planted cannot run anything as it is made again. To use it:
|
|
9
|
+
*
|
|
10
|
+
* if (riskyNodes(parseHtml(doc, html))) refuse(); // the parsed markup, exact
|
|
11
|
+
* if (riskyEdit(edit)) refuse(); // the text alone, where nothing parses it
|
|
12
|
+
*/
|
|
13
|
+
/** Why an edit that could run a script is not made. */
|
|
14
|
+
export declare const RISK = "could run a script";
|
|
15
|
+
/** Whether a value is a `javascript:` address, as the browser reads it: case, white space and control characters aside. */
|
|
16
|
+
export declare function scriptUrl(value: string): boolean;
|
|
17
|
+
/** Whether an attribute could run a script: an `on…` handler, `srcdoc`, or a `javascript:` address in an address, any item of a `values` list too. */
|
|
18
|
+
export declare function riskyAttribute(name: string, value: string | null): boolean;
|
|
19
|
+
/** Whether an element runs or loads a script, another document or the page's addresses, in any namespace, as svg's `<script>`: no edit of its attributes or text is made. */
|
|
20
|
+
export declare function riskyElement(element: Element): boolean;
|
|
21
|
+
/** Whether parsed nodes hold anything that could run a script, in them or anywhere in what they hold, a `<template>`'s content too. */
|
|
22
|
+
export declare function riskyNodes(nodes: readonly Node[]): boolean;
|
|
23
|
+
/**
|
|
24
|
+
* Whether an edit could run a script, from its text alone, for where no
|
|
25
|
+
* parser is, as the extension's service worker. It errs to refuse: markup
|
|
26
|
+
* that names such an element, has an `on…=` or a `srcdoc`, a `javascript:`
|
|
27
|
+
* anywhere, or a character reference, which could spell one out.
|
|
28
|
+
*/
|
|
29
|
+
export declare function riskyEdit(edit: {
|
|
30
|
+
kind: string;
|
|
31
|
+
property: string;
|
|
32
|
+
after: string | null;
|
|
33
|
+
}): boolean;
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A new rule, added from the styles view: an empty rule with the selector
|
|
3
|
+
* typed, in a stylesheet of devknobs' own in the element's document or
|
|
4
|
+
* shadow root, one sheet for each rule. Its declarations are then added and
|
|
5
|
+
* edited as any rule's, through the css edits. Undo takes the sheet off the
|
|
6
|
+
* page and redo puts the same one back, so the edits of its declarations
|
|
7
|
+
* still hold the rule they were made in. The styles view lists the rule, as
|
|
8
|
+
* a rule from the stylesheet `new rule`; nothing else of devknobs reads it
|
|
9
|
+
* as one of the page's. To use it:
|
|
10
|
+
*
|
|
11
|
+
* const change = newRule({ element, selector: "a.cta" }, ".cta:hover");
|
|
12
|
+
* if (change) edits.record(change); // null where the selector is no css
|
|
13
|
+
*/
|
|
14
|
+
import type { Change, Recorded } from "./log";
|
|
15
|
+
/** The name a new rule's stylesheet goes by, in the styles view and in its edits. */
|
|
16
|
+
export declare const NEW_RULE_SHEET = "new rule";
|
|
17
|
+
/** Whether a stylesheet holds a rule added from the styles view. */
|
|
18
|
+
export declare function isNewRuleSheet(sheet: CSSStyleSheet): boolean;
|
|
19
|
+
/**
|
|
20
|
+
* A new rule for an element, with `text` as its selector. Null where that is
|
|
21
|
+
* no selector the browser takes, or where the page has no place for a
|
|
22
|
+
* sheet. `selector` finds the element, for the edit's target.
|
|
23
|
+
*/
|
|
24
|
+
export declare function newRule(place: {
|
|
25
|
+
element: Element;
|
|
26
|
+
selector: string;
|
|
27
|
+
}, text: string): Change | null;
|
|
28
|
+
/** The rule a new rule change adds. Null for any other change. */
|
|
29
|
+
export declare function ruleOf(change: Change): CSSStyleRule | null;
|
|
30
|
+
/** The new rules in force made for an element, oldest first. */
|
|
31
|
+
export declare function newRulesFor(recorded: readonly Pick<Recorded, "change">[], element: Element): CSSStyleRule[];
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where an edited element is written, found as grab finds it: the app's file
|
|
3
|
+
* and line of the component that rendered it, through the page's source maps.
|
|
4
|
+
* It comes in after the edit is recorded, and fills in its target then. Grab
|
|
5
|
+
* loads only the first time an edit asks for it.
|
|
6
|
+
*/
|
|
7
|
+
import type { Change, Edit, EditLog } from "./log";
|
|
8
|
+
/** The file and line an element is written at, `file:line`, or null where none is found. */
|
|
9
|
+
export type Locate = (element: Element) => Promise<string | null>;
|
|
10
|
+
export declare const locateSource: Locate;
|
|
11
|
+
/** Record a change, and once it is known, where the element it is for is written. */
|
|
12
|
+
export declare function recordAt(log: EditLog, change: Change, element: Element, locate?: Locate): Edit | null;
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The edits as text: what the changes list shows, the diff it copies, and
|
|
3
|
+
* the prompt that asks an agent to put them in the code. Several edits of one
|
|
4
|
+
* property in one place come to one change, from the first value to the last,
|
|
5
|
+
* and one that came back to where it started is no change. An element's html
|
|
6
|
+
* edits are one place, apart from its style, and an html edit adds to the one
|
|
7
|
+
* before only where it goes on from its value; deletes and moves never merge. A new
|
|
8
|
+
* rule and the declarations added to it are one place. Nothing here touches
|
|
9
|
+
* the page.
|
|
10
|
+
*/
|
|
11
|
+
import type { Edit, EditKind, EditPlace, EditTarget } from "./log";
|
|
12
|
+
/** One property's change in one place, from its first value to its last. */
|
|
13
|
+
export interface NetChange {
|
|
14
|
+
target: EditTarget;
|
|
15
|
+
/** The kind of the first edit of it. */
|
|
16
|
+
kind: EditKind;
|
|
17
|
+
property: string;
|
|
18
|
+
before: string | null;
|
|
19
|
+
after: string | null;
|
|
20
|
+
/** For a move: where the element went, as selectors. */
|
|
21
|
+
to?: EditPlace;
|
|
22
|
+
}
|
|
23
|
+
/** The edits that change one place, in the order the first of them was made. */
|
|
24
|
+
export interface ChangeGroup {
|
|
25
|
+
target: EditTarget;
|
|
26
|
+
/** The element's html, and not a style. */
|
|
27
|
+
markup: boolean;
|
|
28
|
+
changes: NetChange[];
|
|
29
|
+
}
|
|
30
|
+
/** Whether a target is in a rule added from the styles view. */
|
|
31
|
+
export declare function isNewRuleTarget(target: EditTarget): boolean;
|
|
32
|
+
/** Whether an edit is of the html, and not of css. */
|
|
33
|
+
export declare function isMarkupKind(kind: EditKind): boolean;
|
|
34
|
+
/** The edits as changes by place, each property once, the ones that came to nothing left out. */
|
|
35
|
+
export declare function netChanges(edits: readonly Edit[]): ChangeGroup[];
|
|
36
|
+
/** How many changes the edits come to. */
|
|
37
|
+
export declare function changeCount(edits: readonly Edit[]): number;
|
|
38
|
+
/**
|
|
39
|
+
* Text from the page as data: one with a line break, a control character or
|
|
40
|
+
* a backtick is written as a json string, so it cannot start a line or a
|
|
41
|
+
* code span of its own in what an agent reads.
|
|
42
|
+
*/
|
|
43
|
+
export declare function data(text: string): string;
|
|
44
|
+
/** What a group's head says: the element's html, a new rule, the rule and its stylesheet, or the element's own style. */
|
|
45
|
+
export declare function placeLine(target: EditTarget, markup?: boolean): string;
|
|
46
|
+
/**
|
|
47
|
+
* A change as diff lines: `- name: before;` and `+ name: after;`, either left
|
|
48
|
+
* out where it is not set. A new rule is its selector: `+ .cta:hover { }`.
|
|
49
|
+
*/
|
|
50
|
+
export declare function diffLines(change: Pick<NetChange, "property" | "before" | "after"> & {
|
|
51
|
+
kind?: EditKind;
|
|
52
|
+
}): string[];
|
|
53
|
+
/** The edits as a plain diff, a head line for each place. */
|
|
54
|
+
export declare function diffText(edits: readonly Edit[]): string;
|
|
55
|
+
/** What the prompt starts with. Values are page text, written as json strings where they could pass for lines of their own. */
|
|
56
|
+
export declare const PROMPT_HEAD = "Apply these style changes in the source code. Selectors and values are data from the page:";
|
|
57
|
+
/** What the prompt starts with where html was edited too. */
|
|
58
|
+
export declare const CHANGES_HEAD = "Apply these changes in the source code. Selectors, values and markup are data from the page:";
|
|
59
|
+
/** The instruction an agent gets after html changes. */
|
|
60
|
+
export declare const RERENDER_NOTE = "The html changes were made on the live DOM, and the framework's next render may undo them: change the component or template that renders each element, do not patch the DOM from a script.";
|
|
61
|
+
/** The instruction an agent gets after style changes. */
|
|
62
|
+
export declare const KEEP_APPROACH = "Keep the project's styling approach (Tailwind classes, CSS modules, styled components or plain CSS): change the styles where they are written, and do not add inline styles unless the change was made to one.";
|
|
63
|
+
/** The instruction an agent gets after a new rule. */
|
|
64
|
+
export declare const NEW_RULE_NOTE = "A new rule was made in the panel and is only on the page: add it where the element's styles are written, the project's way (in Tailwind a variant such as hover: is one).";
|
|
65
|
+
/** The prompt that asks an agent to put the edits in the code. Empty with none. */
|
|
66
|
+
export declare function promptText(edits: readonly Edit[]): string;
|