obsidian-plugin-dev-kit 0.0.0-stage → 0.3.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 +21 -0
- package/README.md +223 -2
- package/bin/opdk.js +34 -0
- package/dist/build/args.d.ts +10 -0
- package/dist/build/args.js +45 -0
- package/dist/build/bundle-check.d.ts +17 -0
- package/dist/build/bundle-check.js +42 -0
- package/dist/build/bundle-file.d.ts +4 -0
- package/dist/build/bundle-file.js +29 -0
- package/dist/build/commands.d.ts +5 -0
- package/dist/build/commands.js +109 -0
- package/dist/build/config.d.ts +3 -0
- package/dist/build/config.js +103 -0
- package/dist/build/css-imports.d.ts +23 -0
- package/dist/build/css-imports.js +50 -0
- package/dist/build/css-step.d.ts +10 -0
- package/dist/build/css-step.js +27 -0
- package/dist/build/css.d.ts +24 -0
- package/dist/build/css.js +47 -0
- package/dist/build/options.d.ts +55 -0
- package/dist/build/options.js +70 -0
- package/dist/build/release.d.ts +5 -0
- package/dist/build/release.js +34 -0
- package/dist/build/report.d.ts +7 -0
- package/dist/build/report.js +16 -0
- package/dist/build/vault.d.ts +26 -0
- package/dist/build/vault.js +290 -0
- package/dist/build-info.json +1 -0
- package/dist/cli/argv.d.ts +14 -0
- package/dist/cli/argv.js +18 -0
- package/dist/cli/commands.d.ts +3 -0
- package/dist/cli/commands.js +7 -0
- package/dist/cli/main.d.ts +2 -0
- package/dist/cli/main.js +23 -0
- package/dist/cli/process-reporter.d.ts +5 -0
- package/dist/cli/process-reporter.js +15 -0
- package/dist/cli/registry.d.ts +4 -0
- package/dist/cli/registry.js +15 -0
- package/dist/cli/reporter.d.ts +53 -0
- package/dist/cli/reporter.js +100 -0
- package/dist/cli/run.d.ts +9 -0
- package/dist/cli/run.js +61 -0
- package/dist/cli/types.d.ts +27 -0
- package/dist/cli/types.js +1 -0
- package/dist/cli/version.d.ts +13 -0
- package/dist/cli/version.js +61 -0
- package/dist/config/define-config.d.ts +3 -0
- package/dist/config/define-config.js +4 -0
- package/dist/config/load-config.d.ts +6 -0
- package/dist/config/load-config.js +70 -0
- package/dist/config/manifest.d.ts +3 -0
- package/dist/config/manifest.js +72 -0
- package/dist/config/types.d.ts +146 -0
- package/dist/config/types.js +23 -0
- package/dist/demo/args.d.ts +4 -0
- package/dist/demo/args.js +13 -0
- package/dist/demo/checks.d.ts +56 -0
- package/dist/demo/checks.js +124 -0
- package/dist/demo/commands.d.ts +3 -0
- package/dist/demo/commands.js +65 -0
- package/dist/demo/config.d.ts +57 -0
- package/dist/demo/config.js +337 -0
- package/dist/demo/ffmpeg-run.d.ts +18 -0
- package/dist/demo/ffmpeg-run.js +59 -0
- package/dist/demo/ffmpeg.d.ts +63 -0
- package/dist/demo/ffmpeg.js +111 -0
- package/dist/demo/films.d.ts +46 -0
- package/dist/demo/films.js +134 -0
- package/dist/demo/phone-layout.d.ts +38 -0
- package/dist/demo/phone-layout.js +98 -0
- package/dist/demo/phone-render.d.ts +28 -0
- package/dist/demo/phone-render.js +124 -0
- package/dist/demo/published.d.ts +16 -0
- package/dist/demo/published.js +72 -0
- package/dist/demo/run.d.ts +31 -0
- package/dist/demo/run.js +397 -0
- package/dist/demo/stills.d.ts +21 -0
- package/dist/demo/stills.js +62 -0
- package/dist/e2e/artifacts.d.ts +27 -0
- package/dist/e2e/artifacts.js +90 -0
- package/dist/e2e/cleanup.d.ts +54 -0
- package/dist/e2e/cleanup.js +109 -0
- package/dist/e2e/config.d.ts +9 -0
- package/dist/e2e/config.js +42 -0
- package/dist/e2e/create-test.d.ts +37 -0
- package/dist/e2e/create-test.js +109 -0
- package/dist/e2e/demo/clip.d.ts +21 -0
- package/dist/e2e/demo/clip.js +44 -0
- package/dist/e2e/demo/create-demo.d.ts +42 -0
- package/dist/e2e/demo/create-demo.js +439 -0
- package/dist/e2e/demo/manifest.d.ts +76 -0
- package/dist/e2e/demo/manifest.js +168 -0
- package/dist/e2e/demo/names.d.ts +18 -0
- package/dist/e2e/demo/names.js +44 -0
- package/dist/e2e/demo/options.d.ts +22 -0
- package/dist/e2e/demo/options.js +59 -0
- package/dist/e2e/demo/ownership.d.ts +27 -0
- package/dist/e2e/demo/ownership.js +65 -0
- package/dist/e2e/demo/page-scripts.d.ts +82 -0
- package/dist/e2e/demo/page-scripts.js +250 -0
- package/dist/e2e/demo/png.d.ts +8 -0
- package/dist/e2e/demo/png.js +23 -0
- package/dist/e2e/demo/presets.d.ts +43 -0
- package/dist/e2e/demo/presets.js +20 -0
- package/dist/e2e/demo/privacy.d.ts +18 -0
- package/dist/e2e/demo/privacy.js +30 -0
- package/dist/e2e/demo/still-options.d.ts +22 -0
- package/dist/e2e/demo/still-options.js +68 -0
- package/dist/e2e/demo/types.d.ts +184 -0
- package/dist/e2e/demo/types.js +1 -0
- package/dist/e2e/electron-binary.d.ts +15 -0
- package/dist/e2e/electron-binary.js +30 -0
- package/dist/e2e/fixtures.d.ts +62 -0
- package/dist/e2e/fixtures.js +68 -0
- package/dist/e2e/gate.d.ts +4 -0
- package/dist/e2e/gate.js +8 -0
- package/dist/e2e/global-setup.d.ts +11 -0
- package/dist/e2e/global-setup.js +17 -0
- package/dist/e2e/helpers/commands.d.ts +14 -0
- package/dist/e2e/helpers/commands.js +56 -0
- package/dist/e2e/helpers/create-helpers.d.ts +24 -0
- package/dist/e2e/helpers/create-helpers.js +582 -0
- package/dist/e2e/helpers/device-metrics.d.ts +21 -0
- package/dist/e2e/helpers/device-metrics.js +25 -0
- package/dist/e2e/helpers/ime.d.ts +13 -0
- package/dist/e2e/helpers/ime.js +19 -0
- package/dist/e2e/helpers/layout-page-scripts.d.ts +103 -0
- package/dist/e2e/helpers/layout-page-scripts.js +224 -0
- package/dist/e2e/helpers/layout.d.ts +83 -0
- package/dist/e2e/helpers/layout.js +148 -0
- package/dist/e2e/helpers/mobile.d.ts +31 -0
- package/dist/e2e/helpers/mobile.js +26 -0
- package/dist/e2e/helpers/page-scripts.d.ts +194 -0
- package/dist/e2e/helpers/page-scripts.js +467 -0
- package/dist/e2e/helpers/settings.d.ts +8 -0
- package/dist/e2e/helpers/settings.js +16 -0
- package/dist/e2e/helpers/settle.d.ts +28 -0
- package/dist/e2e/helpers/settle.js +33 -0
- package/dist/e2e/helpers/types.d.ts +193 -0
- package/dist/e2e/helpers/types.js +1 -0
- package/dist/e2e/helpers/view-mode.d.ts +23 -0
- package/dist/e2e/helpers/view-mode.js +35 -0
- package/dist/e2e/index.d.ts +14 -0
- package/dist/e2e/index.js +4 -0
- package/dist/e2e/internals.d.ts +155 -0
- package/dist/e2e/internals.js +8 -0
- package/dist/e2e/obsidian-path.d.ts +17 -0
- package/dist/e2e/obsidian-path.js +31 -0
- package/dist/e2e/options.d.ts +123 -0
- package/dist/e2e/options.js +244 -0
- package/dist/e2e/page-scripts.d.ts +45 -0
- package/dist/e2e/page-scripts.js +53 -0
- package/dist/e2e/peers.d.ts +9 -0
- package/dist/e2e/peers.js +19 -0
- package/dist/e2e/plugins.d.ts +32 -0
- package/dist/e2e/plugins.js +119 -0
- package/dist/e2e/process-tree.d.ts +33 -0
- package/dist/e2e/process-tree.js +133 -0
- package/dist/e2e/readiness.d.ts +23 -0
- package/dist/e2e/readiness.js +63 -0
- package/dist/e2e/seed.d.ts +34 -0
- package/dist/e2e/seed.js +122 -0
- package/dist/e2e/session.d.ts +71 -0
- package/dist/e2e/session.js +266 -0
- package/dist/e2e/vault.d.ts +52 -0
- package/dist/e2e/vault.js +146 -0
- package/dist/e2e/version.d.ts +25 -0
- package/dist/e2e/version.js +40 -0
- package/dist/eslint/index.d.ts +2 -0
- package/dist/eslint/index.js +1 -0
- package/dist/eslint/obsidian-plugin.d.ts +49 -0
- package/dist/eslint/obsidian-plugin.js +115 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.js +1 -0
- package/dist/kit/args.d.ts +7 -0
- package/dist/kit/args.js +21 -0
- package/dist/kit/commands.d.ts +3 -0
- package/dist/kit/commands.js +52 -0
- package/dist/kit/files.d.ts +3 -0
- package/dist/kit/files.js +24 -0
- package/dist/kit/pins.d.ts +89 -0
- package/dist/kit/pins.js +178 -0
- package/dist/kit/remote.d.ts +13 -0
- package/dist/kit/remote.js +33 -0
- package/dist/kit/runners.d.ts +11 -0
- package/dist/kit/runners.js +53 -0
- package/dist/kit/terminal-text.d.ts +6 -0
- package/dist/kit/terminal-text.js +20 -0
- package/dist/kit/upgrade.d.ts +26 -0
- package/dist/kit/upgrade.js +162 -0
- package/dist/peers/resolve.d.ts +8 -0
- package/dist/peers/resolve.js +28 -0
- package/dist/peers/versions.d.ts +30 -0
- package/dist/peers/versions.js +32 -0
- package/dist/release/api-check.d.ts +27 -0
- package/dist/release/api-check.js +119 -0
- package/dist/release/args.d.ts +40 -0
- package/dist/release/args.js +120 -0
- package/dist/release/assets.d.ts +21 -0
- package/dist/release/assets.js +35 -0
- package/dist/release/build-check.d.ts +43 -0
- package/dist/release/build-check.js +184 -0
- package/dist/release/build-script.d.ts +12 -0
- package/dist/release/build-script.js +30 -0
- package/dist/release/build-tagged.d.ts +26 -0
- package/dist/release/build-tagged.js +52 -0
- package/dist/release/bump.d.ts +24 -0
- package/dist/release/bump.js +58 -0
- package/dist/release/changelog.d.ts +25 -0
- package/dist/release/changelog.js +148 -0
- package/dist/release/check.d.ts +38 -0
- package/dist/release/check.js +150 -0
- package/dist/release/commands.d.ts +3 -0
- package/dist/release/commands.js +154 -0
- package/dist/release/committed-tree.d.ts +63 -0
- package/dist/release/committed-tree.js +118 -0
- package/dist/release/config.d.ts +3 -0
- package/dist/release/config.js +28 -0
- package/dist/release/gh-access.d.ts +14 -0
- package/dist/release/gh-access.js +45 -0
- package/dist/release/gh.d.ts +10 -0
- package/dist/release/gh.js +33 -0
- package/dist/release/git.d.ts +49 -0
- package/dist/release/git.js +111 -0
- package/dist/release/interrupt.d.ts +30 -0
- package/dist/release/interrupt.js +60 -0
- package/dist/release/json.d.ts +33 -0
- package/dist/release/json.js +81 -0
- package/dist/release/kit-check.d.ts +8 -0
- package/dist/release/kit-check.js +51 -0
- package/dist/release/manifest-rules.d.ts +23 -0
- package/dist/release/manifest-rules.js +255 -0
- package/dist/release/preflight.d.ts +10 -0
- package/dist/release/preflight.js +65 -0
- package/dist/release/problems.d.ts +24 -0
- package/dist/release/problems.js +11 -0
- package/dist/release/project-files.d.ts +14 -0
- package/dist/release/project-files.js +16 -0
- package/dist/release/publish-command.d.ts +21 -0
- package/dist/release/publish-command.js +83 -0
- package/dist/release/publish-git.d.ts +37 -0
- package/dist/release/publish-git.js +108 -0
- package/dist/release/publish-state.d.ts +29 -0
- package/dist/release/publish-state.js +70 -0
- package/dist/release/publish-verify.d.ts +41 -0
- package/dist/release/publish-verify.js +112 -0
- package/dist/release/publish-wait.d.ts +25 -0
- package/dist/release/publish-wait.js +56 -0
- package/dist/release/publish.d.ts +35 -0
- package/dist/release/publish.js +181 -0
- package/dist/release/release-assets.d.ts +39 -0
- package/dist/release/release-assets.js +68 -0
- package/dist/release/release.d.ts +37 -0
- package/dist/release/release.js +179 -0
- package/dist/release/remote.d.ts +12 -0
- package/dist/release/remote.js +15 -0
- package/dist/release/reproducible.d.ts +16 -0
- package/dist/release/reproducible.js +34 -0
- package/dist/release/run-tests.d.ts +5 -0
- package/dist/release/run-tests.js +17 -0
- package/dist/release/semver.d.ts +8 -0
- package/dist/release/semver.js +60 -0
- package/dist/release/version-rules.d.ts +28 -0
- package/dist/release/version-rules.js +63 -0
- package/dist/release/versions-json.d.ts +15 -0
- package/dist/release/versions-json.js +88 -0
- package/dist/release/workflow-run.d.ts +44 -0
- package/dist/release/workflow-run.js +71 -0
- package/dist/scanner/code-checks.d.ts +41 -0
- package/dist/scanner/code-checks.js +82 -0
- package/dist/scanner/commands.d.ts +3 -0
- package/dist/scanner/commands.js +43 -0
- package/dist/scanner/config.d.ts +7 -0
- package/dist/scanner/config.js +25 -0
- package/dist/scanner/css-check.d.ts +26 -0
- package/dist/scanner/css-check.js +63 -0
- package/dist/scanner/eslint-nesting.d.ts +16 -0
- package/dist/scanner/eslint-nesting.js +45 -0
- package/dist/scanner/findings.d.ts +23 -0
- package/dist/scanner/findings.js +21 -0
- package/dist/scanner/git-files.d.ts +16 -0
- package/dist/scanner/git-files.js +73 -0
- package/dist/scanner/lint.d.ts +47 -0
- package/dist/scanner/lint.js +163 -0
- package/dist/scanner/meta-checks.d.ts +8 -0
- package/dist/scanner/meta-checks.js +22 -0
- package/dist/scanner/outside-project.d.ts +19 -0
- package/dist/scanner/outside-project.js +20 -0
- package/dist/scanner/run.d.ts +19 -0
- package/dist/scanner/run.js +78 -0
- package/dist/scanner/scanner-config.d.ts +114 -0
- package/dist/scanner/scanner-config.js +207 -0
- package/dist/scanner/typescript-gate.d.ts +30 -0
- package/dist/scanner/typescript-gate.js +73 -0
- package/dist/vitest/build-config.d.ts +17 -0
- package/dist/vitest/build-config.js +106 -0
- package/dist/vitest/define-unit-config.d.ts +27 -0
- package/dist/vitest/define-unit-config.js +45 -0
- package/dist/vitest/dom/elements.d.ts +87 -0
- package/dist/vitest/dom/elements.js +291 -0
- package/dist/vitest/dom/index.d.ts +1 -0
- package/dist/vitest/dom/index.js +1 -0
- package/dist/vitest/dom/install.d.ts +8 -0
- package/dist/vitest/dom/install.js +261 -0
- package/dist/vitest/dom/setup.d.ts +1 -0
- package/dist/vitest/dom/setup.js +3 -0
- package/dist/vitest/index.d.ts +3 -0
- package/dist/vitest/index.js +2 -0
- package/dist/vitest/options.d.ts +92 -0
- package/dist/vitest/options.js +136 -0
- package/dist/vitest/peers.d.ts +10 -0
- package/dist/vitest/peers.js +51 -0
- package/dist/vitest/workspace-root.d.ts +7 -0
- package/dist/vitest/workspace-root.js +39 -0
- package/docs/build.md +232 -0
- package/docs/ci.md +182 -0
- package/docs/demo.md +364 -0
- package/docs/e2e.md +563 -0
- package/docs/release.md +374 -0
- package/docs/scanner.md +204 -0
- package/docs/unit.md +291 -0
- package/package.json +100 -4
- package/plugins/opdk/skills/audit/SKILL.md +81 -0
- package/plugins/opdk/skills/build/SKILL.md +79 -0
- package/plugins/opdk/skills/demo/SKILL.md +102 -0
- package/plugins/opdk/skills/e2e/SKILL.md +132 -0
- package/plugins/opdk/skills/release/SKILL.md +84 -0
- package/plugins/opdk/skills/scanner/SKILL.md +60 -0
- package/plugins/opdk/skills/unit/SKILL.md +90 -0
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Page functions of the layout checks (`obsidian.checkLayout()`). Like `page-scripts.ts` each one is serialised, so it
|
|
3
|
+
* is self-contained: only its own source text crosses into the page. They are exported so tests can run them against a
|
|
4
|
+
* fake `document`. The kit's TypeScript has no DOM types, hence the small interfaces below. The code that names an
|
|
5
|
+
* element (`describe`, `where`) is written out in each function for the same reason: no function can call another.
|
|
6
|
+
*/
|
|
7
|
+
/** One thing a layout check found; `where` names the element the way a person finds it (`button.save-button`). */
|
|
8
|
+
export interface LayoutFinding {
|
|
9
|
+
where: string;
|
|
10
|
+
/** What is wrong, with the measured numbers. */
|
|
11
|
+
detail: string;
|
|
12
|
+
}
|
|
13
|
+
/** The result of a page function that needs the root: it may not exist. `total` counts every finding, `findings` holds the first `limit`. */
|
|
14
|
+
export type LayoutResult = {
|
|
15
|
+
rootFound: false;
|
|
16
|
+
} | {
|
|
17
|
+
rootFound: true;
|
|
18
|
+
findings: LayoutFinding[];
|
|
19
|
+
total: number;
|
|
20
|
+
};
|
|
21
|
+
/** At most this many findings of one kind are reported; a broken layout would otherwise list the whole tree. */
|
|
22
|
+
export declare const MAX_FINDINGS_PER_CHECK = 10;
|
|
23
|
+
/** Whether anything matches `selector`. Asked once before any check runs, so a missing root fails even when every check is off. */
|
|
24
|
+
export declare function rootExists(selector: string): boolean;
|
|
25
|
+
/**
|
|
26
|
+
* Elements inside `root` (and `root` itself) that are wider than their box: `scrollWidth > clientWidth + 1`, the
|
|
27
|
+
* same test as for a horizontal scroll bar. Every element is checked, scroll panes included: `overflow-y: auto`
|
|
28
|
+
* makes the computed `overflow-x` auto too, so the computed style cannot tell a pane that scrolls on purpose from
|
|
29
|
+
* one whose content spills sideways. Skipped, because they are not layout bugs:
|
|
30
|
+
* - an element that cuts its text with an ellipsis (`text-overflow: ellipsis`, or `white-space: nowrap` with
|
|
31
|
+
* `overflow: hidden`), which Obsidian does for setting names and tabs;
|
|
32
|
+
* - a visually hidden box (1 px or less, clipped by `overflow`, `clip` or `clip-path`), the "screen reader only" pattern;
|
|
33
|
+
* - an element inside `ignore` (a selector matched against the element and its ancestors).
|
|
34
|
+
*/
|
|
35
|
+
export declare function findOverflow(args: {
|
|
36
|
+
root: string;
|
|
37
|
+
ignore: string | null;
|
|
38
|
+
limit: number;
|
|
39
|
+
}): LayoutResult;
|
|
40
|
+
/**
|
|
41
|
+
* Visible elements inside `root` that match `targetSelector` (and not `ignoreSelector`) and are smaller than `minSize`
|
|
42
|
+
* CSS pixels in either direction, less 0.5 px for rounding. Visible means it has a box (`getClientRects()`, which
|
|
43
|
+
* `position: fixed` elements have too, unlike `offsetParent`) and is not `visibility: hidden`.
|
|
44
|
+
*/
|
|
45
|
+
export declare function findSmallTargets(args: {
|
|
46
|
+
root: string;
|
|
47
|
+
targets: string;
|
|
48
|
+
ignore: string | null;
|
|
49
|
+
minSize: number;
|
|
50
|
+
limit: number;
|
|
51
|
+
}): LayoutResult;
|
|
52
|
+
/**
|
|
53
|
+
* Moves focus to the element that starts a Tab walk and forgets the elements of the last walk. The start is `from`, or
|
|
54
|
+
* else the first element of `root` that can take focus, is shown (has a box, not `visibility: hidden`) and is not
|
|
55
|
+
* disabled. The walk would check nothing if the start sat outside `root` or did not take focus, so both are named.
|
|
56
|
+
*/
|
|
57
|
+
export declare function focusWalkStart(args: {
|
|
58
|
+
root: string;
|
|
59
|
+
from: string | null;
|
|
60
|
+
}): "ok" | "no-root" | "no-start" | "outside-root" | "not-focused";
|
|
61
|
+
/** What the element that has focus looks like: where it is, and whether focus changes anything about it. */
|
|
62
|
+
export interface FocusStop {
|
|
63
|
+
/** False when focus left `root`: the walk is over. */
|
|
64
|
+
inRoot: boolean;
|
|
65
|
+
/** The element was already visited by this walk: focus went round in a circle (a focus trap). */
|
|
66
|
+
repeat: boolean;
|
|
67
|
+
where: string;
|
|
68
|
+
hasRing: boolean;
|
|
69
|
+
detail: string;
|
|
70
|
+
/**
|
|
71
|
+
* Set when `hasRing` is false for an element whose ring Obsidian draws on a vendor pseudo-element that
|
|
72
|
+
* `getComputedStyle` cannot read (the thumb of a range input, the swatch of a colour input): the box to compare as
|
|
73
|
+
* pixels, focused against blurred, with `pixelStep`. Null for every other element.
|
|
74
|
+
*/
|
|
75
|
+
pixelBox: {
|
|
76
|
+
x: number;
|
|
77
|
+
y: number;
|
|
78
|
+
width: number;
|
|
79
|
+
height: number;
|
|
80
|
+
} | null;
|
|
81
|
+
}
|
|
82
|
+
/**
|
|
83
|
+
* Reads the element that has focus. It counts as showing a focus ring only when an outline or a box-shadow differs
|
|
84
|
+
* from the same element without focus: Obsidian gives every button a resting `box-shadow`, so "has a shadow" would
|
|
85
|
+
* pass a button whose ring was removed. Obsidian also draws some rings on a pseudo-element (a `.setting-item` rings
|
|
86
|
+
* itself with `:focus-visible::after`), so the element, its `::before` and its `::after` are all compared; a change
|
|
87
|
+
* in any of them is a ring. Vendor pseudo-elements (`::-webkit-slider-thumb`, `::-webkit-color-swatch`) are not
|
|
88
|
+
* readable: `getComputedStyle` answers with the style of the element itself. A range or colour input without a ring
|
|
89
|
+
* in the readable parts is returned with a `pixelBox`, and the walk compares pixels for it. The
|
|
90
|
+
* element is blurred for the second read and focused again; if it did not take focus back (it was replaced or
|
|
91
|
+
* detached on blur) the walk cannot go on and this throws. Transitions are switched off for both reads, because a
|
|
92
|
+
* style that has just changed would read as the old value. An element inside `ignore` passes without a read.
|
|
93
|
+
*/
|
|
94
|
+
export declare function readFocusStop(args: {
|
|
95
|
+
root: string;
|
|
96
|
+
ignore: string | null;
|
|
97
|
+
}): FocusStop | null;
|
|
98
|
+
/**
|
|
99
|
+
* The page side of the pixel comparison for an element whose ring cannot be read (see `FocusStop.pixelBox`). `begin`
|
|
100
|
+
* switches transitions off, `blur` takes focus away, anything else (`end`) gives it back and removes the style. The caller takes a
|
|
101
|
+
* screenshot between the steps. It is false when `end` finds the element did not take focus back.
|
|
102
|
+
*/
|
|
103
|
+
export declare function pixelStep(step: string): boolean;
|
|
@@ -0,0 +1,224 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Page functions of the layout checks (`obsidian.checkLayout()`). Like `page-scripts.ts` each one is serialised, so it
|
|
3
|
+
* is self-contained: only its own source text crosses into the page. They are exported so tests can run them against a
|
|
4
|
+
* fake `document`. The kit's TypeScript has no DOM types, hence the small interfaces below. The code that names an
|
|
5
|
+
* element (`describe`, `where`) is written out in each function for the same reason: no function can call another.
|
|
6
|
+
*/
|
|
7
|
+
/** At most this many findings of one kind are reported; a broken layout would otherwise list the whole tree. */
|
|
8
|
+
export const MAX_FINDINGS_PER_CHECK = 10;
|
|
9
|
+
/** Whether anything matches `selector`. Asked once before any check runs, so a missing root fails even when every check is off. */
|
|
10
|
+
export function rootExists(selector) {
|
|
11
|
+
const globals = globalThis;
|
|
12
|
+
return (globals.document?.querySelector(selector) ?? null) !== null;
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* Elements inside `root` (and `root` itself) that are wider than their box: `scrollWidth > clientWidth + 1`, the
|
|
16
|
+
* same test as for a horizontal scroll bar. Every element is checked, scroll panes included: `overflow-y: auto`
|
|
17
|
+
* makes the computed `overflow-x` auto too, so the computed style cannot tell a pane that scrolls on purpose from
|
|
18
|
+
* one whose content spills sideways. Skipped, because they are not layout bugs:
|
|
19
|
+
* - an element that cuts its text with an ellipsis (`text-overflow: ellipsis`, or `white-space: nowrap` with
|
|
20
|
+
* `overflow: hidden`), which Obsidian does for setting names and tabs;
|
|
21
|
+
* - a visually hidden box (1 px or less, clipped by `overflow`, `clip` or `clip-path`), the "screen reader only" pattern;
|
|
22
|
+
* - an element inside `ignore` (a selector matched against the element and its ancestors).
|
|
23
|
+
*/
|
|
24
|
+
export function findOverflow(args) {
|
|
25
|
+
const globals = globalThis;
|
|
26
|
+
const root = globals.document?.querySelector(args.root) ?? null;
|
|
27
|
+
if (root === null) {
|
|
28
|
+
return { rootFound: false };
|
|
29
|
+
}
|
|
30
|
+
const describe = (element) => {
|
|
31
|
+
const classes = typeof element.className === "string" ? element.className.trim().split(/\s+/).filter((name) => name !== "") : [];
|
|
32
|
+
return element.tagName.toLowerCase() + (element.id === "" ? "" : `#${element.id}`) + classes.map((name) => `.${name}`).join("");
|
|
33
|
+
};
|
|
34
|
+
const findings = [];
|
|
35
|
+
let total = 0;
|
|
36
|
+
for (const element of [root, ...Array.from(root.querySelectorAll("*"))]) {
|
|
37
|
+
if (element.scrollWidth <= element.clientWidth + 1) {
|
|
38
|
+
continue;
|
|
39
|
+
}
|
|
40
|
+
if (args.ignore !== null && element.closest(args.ignore) !== null) {
|
|
41
|
+
continue;
|
|
42
|
+
}
|
|
43
|
+
const style = globals.getComputedStyle?.(element);
|
|
44
|
+
if (style !== undefined) {
|
|
45
|
+
const clips = (value) => value === "hidden" || value === "clip";
|
|
46
|
+
const ellipsis = style.textOverflow === "ellipsis" || (style.whiteSpace === "nowrap" && clips(style.overflowX));
|
|
47
|
+
const tiny = element.clientWidth <= 1 || element.clientHeight <= 1;
|
|
48
|
+
const cut = clips(style.overflowX) || clips(style.overflowY) || (style.clipPath !== "none" && style.clipPath !== "") || (style.clip !== "auto" && style.clip !== "");
|
|
49
|
+
if (ellipsis || (tiny && cut)) {
|
|
50
|
+
continue;
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
total += 1;
|
|
54
|
+
if (findings.length < args.limit) {
|
|
55
|
+
findings.push({ where: describe(element), detail: `scrollWidth ${String(element.scrollWidth)} > clientWidth ${String(element.clientWidth)}` });
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
return { rootFound: true, findings, total };
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* Visible elements inside `root` that match `targetSelector` (and not `ignoreSelector`) and are smaller than `minSize`
|
|
62
|
+
* CSS pixels in either direction, less 0.5 px for rounding. Visible means it has a box (`getClientRects()`, which
|
|
63
|
+
* `position: fixed` elements have too, unlike `offsetParent`) and is not `visibility: hidden`.
|
|
64
|
+
*/
|
|
65
|
+
export function findSmallTargets(args) {
|
|
66
|
+
const globals = globalThis;
|
|
67
|
+
const root = globals.document?.querySelector(args.root) ?? null;
|
|
68
|
+
if (root === null) {
|
|
69
|
+
return { rootFound: false };
|
|
70
|
+
}
|
|
71
|
+
const describe = (element) => {
|
|
72
|
+
const classes = typeof element.className === "string" ? element.className.trim().split(/\s+/).filter((name) => name !== "") : [];
|
|
73
|
+
return element.tagName.toLowerCase() + (element.id === "" ? "" : `#${element.id}`) + classes.map((name) => `.${name}`).join("");
|
|
74
|
+
};
|
|
75
|
+
const findings = [];
|
|
76
|
+
let total = 0;
|
|
77
|
+
for (const element of Array.from(root.querySelectorAll(args.targets))) {
|
|
78
|
+
// A hidden element has no box; it cannot be tapped, so its size does not matter.
|
|
79
|
+
if (element.getClientRects().length === 0 || globals.getComputedStyle?.(element).visibility === "hidden" || (args.ignore !== null && element.closest(args.ignore) !== null)) {
|
|
80
|
+
continue;
|
|
81
|
+
}
|
|
82
|
+
const box = element.getBoundingClientRect();
|
|
83
|
+
if (box.width < args.minSize - 0.5 || box.height < args.minSize - 0.5) {
|
|
84
|
+
total += 1;
|
|
85
|
+
if (findings.length < args.limit) {
|
|
86
|
+
findings.push({ where: describe(element), detail: `${String(Math.round(box.width))} x ${String(Math.round(box.height))} px` });
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
return { rootFound: true, findings, total };
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* Moves focus to the element that starts a Tab walk and forgets the elements of the last walk. The start is `from`, or
|
|
94
|
+
* else the first element of `root` that can take focus, is shown (has a box, not `visibility: hidden`) and is not
|
|
95
|
+
* disabled. The walk would check nothing if the start sat outside `root` or did not take focus, so both are named.
|
|
96
|
+
*/
|
|
97
|
+
export function focusWalkStart(args) {
|
|
98
|
+
const globals = globalThis;
|
|
99
|
+
const root = globals.document?.querySelector(args.root) ?? null;
|
|
100
|
+
if (root === null) {
|
|
101
|
+
return "no-root";
|
|
102
|
+
}
|
|
103
|
+
const shown = (element) => element.getClientRects().length > 0 && globals.getComputedStyle?.(element).visibility !== "hidden";
|
|
104
|
+
const focusable = 'a[href], button, input, select, textarea, summary, [tabindex]:not([tabindex="-1"])';
|
|
105
|
+
const start = args.from === null ? (Array.from(root.querySelectorAll(focusable)).find((element) => shown(element) && element.disabled !== true) ?? null) : (globals.document?.querySelector(args.from) ?? null);
|
|
106
|
+
if (start === null) {
|
|
107
|
+
return "no-start";
|
|
108
|
+
}
|
|
109
|
+
if (!root.contains(start)) {
|
|
110
|
+
return "outside-root";
|
|
111
|
+
}
|
|
112
|
+
start.focus();
|
|
113
|
+
if (globals.document?.activeElement !== start) {
|
|
114
|
+
return "not-focused";
|
|
115
|
+
}
|
|
116
|
+
globals.__opdkFocusSeen = new WeakSet();
|
|
117
|
+
return "ok";
|
|
118
|
+
}
|
|
119
|
+
/**
|
|
120
|
+
* Reads the element that has focus. It counts as showing a focus ring only when an outline or a box-shadow differs
|
|
121
|
+
* from the same element without focus: Obsidian gives every button a resting `box-shadow`, so "has a shadow" would
|
|
122
|
+
* pass a button whose ring was removed. Obsidian also draws some rings on a pseudo-element (a `.setting-item` rings
|
|
123
|
+
* itself with `:focus-visible::after`), so the element, its `::before` and its `::after` are all compared; a change
|
|
124
|
+
* in any of them is a ring. Vendor pseudo-elements (`::-webkit-slider-thumb`, `::-webkit-color-swatch`) are not
|
|
125
|
+
* readable: `getComputedStyle` answers with the style of the element itself. A range or colour input without a ring
|
|
126
|
+
* in the readable parts is returned with a `pixelBox`, and the walk compares pixels for it. The
|
|
127
|
+
* element is blurred for the second read and focused again; if it did not take focus back (it was replaced or
|
|
128
|
+
* detached on blur) the walk cannot go on and this throws. Transitions are switched off for both reads, because a
|
|
129
|
+
* style that has just changed would read as the old value. An element inside `ignore` passes without a read.
|
|
130
|
+
*/
|
|
131
|
+
export function readFocusStop(args) {
|
|
132
|
+
const globals = globalThis;
|
|
133
|
+
const root = globals.document?.querySelector(args.root) ?? null;
|
|
134
|
+
const element = globals.document?.activeElement ?? null;
|
|
135
|
+
if (root === null || element === null || globals.document === undefined || globals.getComputedStyle === undefined) {
|
|
136
|
+
return null;
|
|
137
|
+
}
|
|
138
|
+
const classes = typeof element.className === "string" ? element.className.trim().split(/\s+/).filter((name) => name !== "") : [];
|
|
139
|
+
const where = element.tagName.toLowerCase() + (element.id === "" ? "" : `#${element.id}`) + classes.map((name) => `.${name}`).join("");
|
|
140
|
+
const seen = (globals.__opdkFocusSeen ??= new WeakSet());
|
|
141
|
+
const repeat = seen.has(element);
|
|
142
|
+
seen.add(element);
|
|
143
|
+
const inRoot = root.contains(element);
|
|
144
|
+
if (!inRoot) {
|
|
145
|
+
return { inRoot, repeat, where, hasRing: true, detail: "outside the root", pixelBox: null };
|
|
146
|
+
}
|
|
147
|
+
if (args.ignore !== null && element.closest(args.ignore) !== null) {
|
|
148
|
+
return { inRoot, repeat, where, hasRing: true, detail: "ignored", pixelBox: null };
|
|
149
|
+
}
|
|
150
|
+
const quiet = globals.document.createElement("style");
|
|
151
|
+
quiet.textContent = "*, *::before, *::after { transition: none !important; animation: none !important; }";
|
|
152
|
+
globals.document.documentElement.append(quiet);
|
|
153
|
+
const parts = ["", "::before", "::after"];
|
|
154
|
+
const vendorRing = element.tagName.toLowerCase() === "input" && (element.type === "range" || element.type === "color");
|
|
155
|
+
const read = () => parts.map((part) => {
|
|
156
|
+
const style = globals.getComputedStyle?.(element, part === "" ? undefined : part);
|
|
157
|
+
return {
|
|
158
|
+
outline: style === undefined ? "" : `${style.outlineStyle} ${style.outlineWidth} ${style.outlineColor} offset ${style.outlineOffset}`,
|
|
159
|
+
outlineVisible: style !== undefined && style.outlineStyle !== "none" && Number.parseFloat(style.outlineWidth) > 0,
|
|
160
|
+
shadow: style === undefined || style.boxShadow === "" ? "none" : style.boxShadow,
|
|
161
|
+
};
|
|
162
|
+
});
|
|
163
|
+
try {
|
|
164
|
+
const focused = read();
|
|
165
|
+
element.blur();
|
|
166
|
+
const plain = read();
|
|
167
|
+
element.focus();
|
|
168
|
+
if (globals.document.activeElement !== element) {
|
|
169
|
+
throw new Error(`${where} did not take focus back after the focus ring check blurred it: it was replaced or detached on blur, so the Tab walk cannot go on. Add it to focusRing.ignore, or keep the element in place on blur.`);
|
|
170
|
+
}
|
|
171
|
+
const ring = focused.some((now, index) => {
|
|
172
|
+
const before = plain[index];
|
|
173
|
+
return before !== undefined && ((now.outlineVisible && now.outline !== before.outline) || (now.shadow !== "none" && now.shadow !== before.shadow));
|
|
174
|
+
});
|
|
175
|
+
const own = focused[0];
|
|
176
|
+
const box = element.getBoundingClientRect();
|
|
177
|
+
return {
|
|
178
|
+
inRoot,
|
|
179
|
+
repeat,
|
|
180
|
+
where,
|
|
181
|
+
hasRing: ring,
|
|
182
|
+
pixelBox: !ring && vendorRing ? { x: box.x, y: box.y, width: box.width, height: box.height } : null,
|
|
183
|
+
detail: `focus changes neither the outline (${(own?.outline ?? "").replace(/ offset .*$/, "")}) nor the box-shadow (${own?.shadow ?? "none"}), on the element or its ${parts.slice(1).join(", ")}`,
|
|
184
|
+
};
|
|
185
|
+
}
|
|
186
|
+
finally {
|
|
187
|
+
quiet.remove();
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
/**
|
|
191
|
+
* The page side of the pixel comparison for an element whose ring cannot be read (see `FocusStop.pixelBox`). `begin`
|
|
192
|
+
* switches transitions off, `blur` takes focus away, anything else (`end`) gives it back and removes the style. The caller takes a
|
|
193
|
+
* screenshot between the steps. It is false when `end` finds the element did not take focus back.
|
|
194
|
+
*/
|
|
195
|
+
export function pixelStep(step) {
|
|
196
|
+
const globals = globalThis;
|
|
197
|
+
const doc = globals.document;
|
|
198
|
+
if (doc === undefined) {
|
|
199
|
+
return false;
|
|
200
|
+
}
|
|
201
|
+
if (step === "begin") {
|
|
202
|
+
const element = doc.activeElement;
|
|
203
|
+
if (element === null) {
|
|
204
|
+
return false;
|
|
205
|
+
}
|
|
206
|
+
const quiet = doc.createElement("style");
|
|
207
|
+
quiet.textContent = "*, *::before, *::after { transition: none !important; animation: none !important; }";
|
|
208
|
+
doc.documentElement.append(quiet);
|
|
209
|
+
globals.__opdkPixel = { element, quiet };
|
|
210
|
+
return true;
|
|
211
|
+
}
|
|
212
|
+
const state = globals.__opdkPixel;
|
|
213
|
+
if (state === undefined) {
|
|
214
|
+
return false;
|
|
215
|
+
}
|
|
216
|
+
if (step === "blur") {
|
|
217
|
+
state.element.blur();
|
|
218
|
+
return true;
|
|
219
|
+
}
|
|
220
|
+
state.element.focus();
|
|
221
|
+
state.quiet.remove();
|
|
222
|
+
Reflect.deleteProperty(globals, "__opdkPixel");
|
|
223
|
+
return doc.activeElement === state.element;
|
|
224
|
+
}
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
import type { LayoutFinding } from "./layout-page-scripts.js";
|
|
2
|
+
/** Smaller than this, in CSS pixels, is hard to hit with a thumb (Apple's and Material's guidance is 44 and 48). */
|
|
3
|
+
export declare const DEFAULT_MIN_TOUCH_SIZE = 44;
|
|
4
|
+
/** Elements the touch check looks at when the spec does not say: what a finger presses. */
|
|
5
|
+
export declare const DEFAULT_TOUCH_TARGETS = "button, a[href], select, input:not([type=\"hidden\"]), textarea, summary, [role=\"button\"], [role=\"tab\"], [role=\"menuitem\"]";
|
|
6
|
+
export declare const DEFAULT_MAX_FOCUS_STOPS = 20;
|
|
7
|
+
export interface TouchTargetOptions {
|
|
8
|
+
/** Smallest width and height, in CSS pixels. Default 44. */
|
|
9
|
+
minSize?: number;
|
|
10
|
+
/** CSS selector of what counts as a target inside `root`. Default: buttons, links, selects, inputs, textareas, summaries and elements with role button, tab or menuitem. */
|
|
11
|
+
selector?: string;
|
|
12
|
+
/** CSS selector of targets to leave out, matched against the target and its ancestors (a checkbox that is drawn small inside a larger row). */
|
|
13
|
+
ignore?: string;
|
|
14
|
+
}
|
|
15
|
+
export interface OverflowOptions {
|
|
16
|
+
/** CSS selector of elements to leave out, matched against the element and its ancestors (a code block or a table that scrolls on purpose). */
|
|
17
|
+
ignore?: string;
|
|
18
|
+
}
|
|
19
|
+
export interface FocusRingOptions {
|
|
20
|
+
/** CSS selector of the element where the Tab walk starts. Default: the first element of `root` that can take focus. */
|
|
21
|
+
from?: string;
|
|
22
|
+
/** The walk ends after this many Tab presses if focus has not left `root` by then. Default 20, at most 100. */
|
|
23
|
+
maxStops?: number;
|
|
24
|
+
/** Report it when Tab moves focus out of `root`, as for a modal that must trap focus. Default false: leaving ends the walk without a problem. */
|
|
25
|
+
stayInside?: boolean;
|
|
26
|
+
/** CSS selector of elements the ring check skips (matched against the element and its ancestors), for a control that is replaced on blur or draws its focus state some other way. */
|
|
27
|
+
ignore?: string;
|
|
28
|
+
}
|
|
29
|
+
/** What `obsidian.checkLayout()` and `obsidian.layoutProblems()` look at. Every check can be turned off. */
|
|
30
|
+
export interface LayoutCheckOptions {
|
|
31
|
+
/** CSS selector of the part of the window to check: a modal, a view, a settings tab. Required, so a check never passes by looking at nothing. */
|
|
32
|
+
root: string;
|
|
33
|
+
/** No horizontal overflow inside `root` (`scrollWidth > clientWidth + 1`), scroll panes included. Default true. */
|
|
34
|
+
overflow?: boolean | OverflowOptions;
|
|
35
|
+
/** Touch targets of at least 44 px. Default: on when the window is in the mobile emulation (`obsidian.mobile()`), off otherwise. */
|
|
36
|
+
touchTargets?: boolean | TouchTargetOptions;
|
|
37
|
+
/** Every Tab stop inside `root` shows a focus ring (focus changes an outline or a box-shadow of the element or its ::before/::after). Default false, because it presses Tab and moves focus. */
|
|
38
|
+
focusRing?: boolean | FocusRingOptions;
|
|
39
|
+
}
|
|
40
|
+
export type LayoutCheckName = "overflow" | "touch-target" | "focus-ring" | "focus-escape";
|
|
41
|
+
/** One thing that is wrong, with the check that found it. */
|
|
42
|
+
export interface LayoutProblem extends LayoutFinding {
|
|
43
|
+
check: LayoutCheckName;
|
|
44
|
+
}
|
|
45
|
+
export interface ResolvedLayoutOptions {
|
|
46
|
+
readonly root: string;
|
|
47
|
+
readonly overflow: {
|
|
48
|
+
enabled: boolean;
|
|
49
|
+
ignore: string | null;
|
|
50
|
+
};
|
|
51
|
+
/** Null: not given, decided from the window (mobile or not). */
|
|
52
|
+
readonly touch: {
|
|
53
|
+
enabled: boolean | null;
|
|
54
|
+
minSize: number;
|
|
55
|
+
selector: string;
|
|
56
|
+
ignore: string | null;
|
|
57
|
+
};
|
|
58
|
+
readonly focus: {
|
|
59
|
+
enabled: boolean;
|
|
60
|
+
from: string | null;
|
|
61
|
+
maxStops: number;
|
|
62
|
+
stayInside: boolean;
|
|
63
|
+
ignore: string | null;
|
|
64
|
+
};
|
|
65
|
+
}
|
|
66
|
+
/** Checks the options a spec passed (it may be plain JavaScript or a cast) and fills in the defaults. */
|
|
67
|
+
export declare function resolveLayoutOptions(options: unknown): ResolvedLayoutOptions;
|
|
68
|
+
export declare function rootMissingMessage(root: string): string;
|
|
69
|
+
export declare function noChecksMessage(): string;
|
|
70
|
+
/** Why a Tab walk could not start, as a sentence that says what to do. */
|
|
71
|
+
export declare function focusStartMessage(outcome: "no-start" | "outside-root" | "not-focused", root: string, from: string | null): string;
|
|
72
|
+
/** Cut a problem list to `limit` per kind. The totals of the kinds that were cut go back, so the failure can say "first 10 of N". */
|
|
73
|
+
export declare function capProblems(problems: readonly LayoutProblem[], limit: number): {
|
|
74
|
+
problems: LayoutProblem[];
|
|
75
|
+
cuts: LayoutCut[];
|
|
76
|
+
};
|
|
77
|
+
/** A kind of problem that has more findings than the list shows. */
|
|
78
|
+
export interface LayoutCut {
|
|
79
|
+
check: LayoutCheckName;
|
|
80
|
+
total: number;
|
|
81
|
+
}
|
|
82
|
+
/** The failure text: one line per problem, so a run lists everything that is wrong at once. */
|
|
83
|
+
export declare function layoutFailureMessage(root: string, problems: readonly LayoutProblem[], minSize: number, cuts?: readonly LayoutCut[]): string;
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
/** Smaller than this, in CSS pixels, is hard to hit with a thumb (Apple's and Material's guidance is 44 and 48). */
|
|
2
|
+
export const DEFAULT_MIN_TOUCH_SIZE = 44;
|
|
3
|
+
/** Elements the touch check looks at when the spec does not say: what a finger presses. */
|
|
4
|
+
export const DEFAULT_TOUCH_TARGETS = 'button, a[href], select, input:not([type="hidden"]), textarea, summary, [role="button"], [role="tab"], [role="menuitem"]';
|
|
5
|
+
export const DEFAULT_MAX_FOCUS_STOPS = 20;
|
|
6
|
+
const KNOWN_KEYS = ["root", "overflow", "touchTargets", "focusRing"];
|
|
7
|
+
const TOUCH_KEYS = ["minSize", "selector", "ignore"];
|
|
8
|
+
const OVERFLOW_KEYS = ["ignore"];
|
|
9
|
+
const FOCUS_KEYS = ["from", "maxStops", "stayInside", "ignore"];
|
|
10
|
+
function isRecord(value) {
|
|
11
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
12
|
+
}
|
|
13
|
+
function rejectUnknown(value, allowed, label) {
|
|
14
|
+
const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
|
|
15
|
+
if (unknown.length > 0) {
|
|
16
|
+
throw new Error(`checkLayout(): unknown key(s) in ${label}: ${unknown.join(", ")}. Allowed keys: ${allowed.join(", ")}.`);
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
function optionalSelector(value, label) {
|
|
20
|
+
if (value === undefined) {
|
|
21
|
+
return null;
|
|
22
|
+
}
|
|
23
|
+
if (typeof value !== "string" || value.trim() === "") {
|
|
24
|
+
throw new Error(`checkLayout(): ${label} must be a non-empty CSS selector, got ${JSON.stringify(value)}.`);
|
|
25
|
+
}
|
|
26
|
+
return value;
|
|
27
|
+
}
|
|
28
|
+
/** Checks the options a spec passed (it may be plain JavaScript or a cast) and fills in the defaults. */
|
|
29
|
+
export function resolveLayoutOptions(options) {
|
|
30
|
+
if (!isRecord(options)) {
|
|
31
|
+
throw new Error('checkLayout(): pass an object with the root to check, for example checkLayout({ root: ".modal" }).');
|
|
32
|
+
}
|
|
33
|
+
rejectUnknown(options, KNOWN_KEYS, "the options");
|
|
34
|
+
const root = optionalSelector(options.root, "root");
|
|
35
|
+
if (root === null) {
|
|
36
|
+
throw new Error('checkLayout(): root is required, the CSS selector of the part of the window to check, for example checkLayout({ root: ".modal" }).');
|
|
37
|
+
}
|
|
38
|
+
const { overflow, touchTargets, focusRing } = options;
|
|
39
|
+
const touch = resolveTouch(touchTargets);
|
|
40
|
+
const focus = resolveFocus(focusRing);
|
|
41
|
+
return { root, overflow: resolveOverflow(overflow), touch, focus };
|
|
42
|
+
}
|
|
43
|
+
function resolveOverflow(value) {
|
|
44
|
+
if (value === undefined || typeof value === "boolean") {
|
|
45
|
+
return { enabled: value ?? true, ignore: null };
|
|
46
|
+
}
|
|
47
|
+
if (!isRecord(value)) {
|
|
48
|
+
throw new Error(`checkLayout(): overflow must be true, false or an object { ignore? }, got ${JSON.stringify(value)}.`);
|
|
49
|
+
}
|
|
50
|
+
rejectUnknown(value, OVERFLOW_KEYS, "overflow");
|
|
51
|
+
return { enabled: true, ignore: optionalSelector(value.ignore, "overflow.ignore") };
|
|
52
|
+
}
|
|
53
|
+
function resolveTouch(value) {
|
|
54
|
+
const defaults = { minSize: DEFAULT_MIN_TOUCH_SIZE, selector: DEFAULT_TOUCH_TARGETS, ignore: null };
|
|
55
|
+
if (value === undefined) {
|
|
56
|
+
return { enabled: null, ...defaults };
|
|
57
|
+
}
|
|
58
|
+
if (typeof value === "boolean") {
|
|
59
|
+
return { enabled: value, ...defaults };
|
|
60
|
+
}
|
|
61
|
+
if (!isRecord(value)) {
|
|
62
|
+
throw new Error(`checkLayout(): touchTargets must be true, false or an object { minSize?, selector?, ignore? }, got ${JSON.stringify(value)}.`);
|
|
63
|
+
}
|
|
64
|
+
rejectUnknown(value, TOUCH_KEYS, "touchTargets");
|
|
65
|
+
const { minSize } = value;
|
|
66
|
+
if (minSize !== undefined && (typeof minSize !== "number" || !Number.isFinite(minSize) || minSize <= 0)) {
|
|
67
|
+
throw new Error(`checkLayout(): touchTargets.minSize must be a number of CSS pixels above 0, got ${JSON.stringify(minSize)}.`);
|
|
68
|
+
}
|
|
69
|
+
return {
|
|
70
|
+
enabled: true,
|
|
71
|
+
minSize: minSize ?? DEFAULT_MIN_TOUCH_SIZE,
|
|
72
|
+
selector: optionalSelector(value.selector, "touchTargets.selector") ?? DEFAULT_TOUCH_TARGETS,
|
|
73
|
+
ignore: optionalSelector(value.ignore, "touchTargets.ignore"),
|
|
74
|
+
};
|
|
75
|
+
}
|
|
76
|
+
function resolveFocus(value) {
|
|
77
|
+
if (value === undefined || typeof value === "boolean") {
|
|
78
|
+
return { enabled: value ?? false, from: null, maxStops: DEFAULT_MAX_FOCUS_STOPS, stayInside: false, ignore: null };
|
|
79
|
+
}
|
|
80
|
+
if (!isRecord(value)) {
|
|
81
|
+
throw new Error(`checkLayout(): focusRing must be true, false or an object { from?, maxStops?, stayInside?, ignore? }, got ${JSON.stringify(value)}.`);
|
|
82
|
+
}
|
|
83
|
+
rejectUnknown(value, FOCUS_KEYS, "focusRing");
|
|
84
|
+
const { maxStops } = value;
|
|
85
|
+
if (maxStops !== undefined && (typeof maxStops !== "number" || !Number.isInteger(maxStops) || maxStops < 1 || maxStops > 100)) {
|
|
86
|
+
throw new Error(`checkLayout(): focusRing.maxStops must be a whole number from 1 to 100, got ${JSON.stringify(maxStops)}.`);
|
|
87
|
+
}
|
|
88
|
+
const { stayInside } = value;
|
|
89
|
+
if (stayInside !== undefined && typeof stayInside !== "boolean") {
|
|
90
|
+
throw new Error(`checkLayout(): focusRing.stayInside must be true or false, got ${JSON.stringify(stayInside)}.`);
|
|
91
|
+
}
|
|
92
|
+
return { enabled: true, from: optionalSelector(value.from, "focusRing.from"), maxStops: maxStops ?? DEFAULT_MAX_FOCUS_STOPS, stayInside: stayInside ?? false, ignore: optionalSelector(value.ignore, "focusRing.ignore") };
|
|
93
|
+
}
|
|
94
|
+
export function rootMissingMessage(root) {
|
|
95
|
+
return `checkLayout(): nothing matches the root ${JSON.stringify(root)}. Open the part of the window you want to check before the call, and check the selector.`;
|
|
96
|
+
}
|
|
97
|
+
export function noChecksMessage() {
|
|
98
|
+
return "checkLayout(): nothing to check. Every check is off (touch targets are only on by default in the mobile emulation). Turn one on: overflow, touchTargets or focusRing.";
|
|
99
|
+
}
|
|
100
|
+
/** Why a Tab walk could not start, as a sentence that says what to do. */
|
|
101
|
+
export function focusStartMessage(outcome, root, from) {
|
|
102
|
+
if (outcome === "outside-root") {
|
|
103
|
+
return `checkLayout(): focusRing.from ${JSON.stringify(from)} is not inside ${JSON.stringify(root)}, so the walk would check nothing of it. Pick an element inside the root.`;
|
|
104
|
+
}
|
|
105
|
+
if (outcome === "not-focused") {
|
|
106
|
+
return `checkLayout(): the element where the Tab walk starts${from === null ? "" : ` (${JSON.stringify(from)})`} did not take focus. Pick a focusable element inside ${JSON.stringify(root)} (a button, a link, an input, or tabindex="0").`;
|
|
107
|
+
}
|
|
108
|
+
return from === null
|
|
109
|
+
? `checkLayout(): nothing inside ${JSON.stringify(root)} can take focus (no visible, enabled button, link, input, select or tabindex="0"), so there are no Tab stops to check. Turn focusRing off, or check the selector.`
|
|
110
|
+
: `checkLayout(): focusRing.from ${JSON.stringify(from)} matches nothing. Check the selector.`;
|
|
111
|
+
}
|
|
112
|
+
/** Cut a problem list to `limit` per kind. The totals of the kinds that were cut go back, so the failure can say "first 10 of N". */
|
|
113
|
+
export function capProblems(problems, limit) {
|
|
114
|
+
const kept = [];
|
|
115
|
+
const totals = new Map();
|
|
116
|
+
for (const problem of problems) {
|
|
117
|
+
const total = (totals.get(problem.check) ?? 0) + 1;
|
|
118
|
+
totals.set(problem.check, total);
|
|
119
|
+
if (total <= limit) {
|
|
120
|
+
kept.push(problem);
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
return { problems: kept, cuts: [...totals].filter(([, total]) => total > limit).map(([check, total]) => ({ check, total })) };
|
|
124
|
+
}
|
|
125
|
+
const LABELS = {
|
|
126
|
+
overflow: "horizontal overflow",
|
|
127
|
+
"touch-target": "touch target too small",
|
|
128
|
+
"focus-ring": "no focus ring",
|
|
129
|
+
"focus-escape": "focus left the root",
|
|
130
|
+
};
|
|
131
|
+
/** The failure text: one line per problem, so a run lists everything that is wrong at once. */
|
|
132
|
+
export function layoutFailureMessage(root, problems, minSize, cuts = []) {
|
|
133
|
+
const lines = problems.map((problem) => ` - ${LABELS[problem.check]}: ${problem.where} (${problem.detail})`);
|
|
134
|
+
for (const cut of cuts) {
|
|
135
|
+
lines.push(` - ${LABELS[cut.check]}: (first ${String(problems.filter((problem) => problem.check === cut.check).length)} of ${String(cut.total)})`);
|
|
136
|
+
}
|
|
137
|
+
const hints = [];
|
|
138
|
+
if (problems.some((problem) => problem.check === "touch-target")) {
|
|
139
|
+
hints.push(`Touch targets must be at least ${String(minSize)} px; raise the size in CSS for the mobile layout, or pass touchTargets: { ignore } for an element that is not a target.`);
|
|
140
|
+
}
|
|
141
|
+
if (problems.some((problem) => problem.check === "focus-ring")) {
|
|
142
|
+
hints.push("A focus ring is an outline or a box-shadow that focus changes, on the element or its ::before/::after (a resting box-shadow does not count); a theme that sets outline: none needs a replacement.");
|
|
143
|
+
}
|
|
144
|
+
if (problems.some((problem) => problem.check === "focus-escape")) {
|
|
145
|
+
hints.push("Keep Tab inside a modal: focus the first control again when Tab leaves the last one.");
|
|
146
|
+
}
|
|
147
|
+
return [`checkLayout(): ${String(problems.length)} ${problems.length === 1 ? "problem" : "problems"} inside ${JSON.stringify(root)}:`, ...lines, ...hints].join("\n");
|
|
148
|
+
}
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
/** The phone the emulation produces unless asked otherwise (an iPhone 14 viewport at twice the pixel density). */
|
|
2
|
+
export declare const DEFAULT_PHONE: {
|
|
3
|
+
readonly width: 390;
|
|
4
|
+
readonly height: 844;
|
|
5
|
+
readonly scale: 2;
|
|
6
|
+
};
|
|
7
|
+
export interface MobileOptions {
|
|
8
|
+
/** CSS pixels. Default 390. */
|
|
9
|
+
width?: number;
|
|
10
|
+
/** CSS pixels. Default 844. */
|
|
11
|
+
height?: number;
|
|
12
|
+
/** Device pixel ratio: sets the page's scale. `win.screenshot()` still uses the display's ratio unless called with `{ scale: "css" }`. Default 2. */
|
|
13
|
+
scale?: number;
|
|
14
|
+
}
|
|
15
|
+
export interface DeviceMetrics {
|
|
16
|
+
readonly width: number;
|
|
17
|
+
readonly height: number;
|
|
18
|
+
readonly deviceScaleFactor: number;
|
|
19
|
+
readonly mobile: false;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* The parameters of CDP `Emulation.setDeviceMetricsOverride`. `mobile` stays false on purpose: Chromium's own mobile
|
|
23
|
+
* mode adds touch events and a meta-viewport pass that Obsidian's `emulateMobile` does not expect; the override only
|
|
24
|
+
* has to make the viewport phone-sized, and `emulateMobile(true)` does the rest.
|
|
25
|
+
*/
|
|
26
|
+
export declare function deviceMetrics(options?: MobileOptions): DeviceMetrics;
|
|
27
|
+
/**
|
|
28
|
+
* True for the errors a page call raises because the page reloaded under it. `emulateMobile()` reloads the window,
|
|
29
|
+
* so the call that started it never returns; that is the only rejection `mobile()` and `desktop()` accept.
|
|
30
|
+
*/
|
|
31
|
+
export declare function isReloadRejection(error: unknown): boolean;
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
/** The phone the emulation produces unless asked otherwise (an iPhone 14 viewport at twice the pixel density). */
|
|
2
|
+
export const DEFAULT_PHONE = { width: 390, height: 844, scale: 2 };
|
|
3
|
+
/**
|
|
4
|
+
* The parameters of CDP `Emulation.setDeviceMetricsOverride`. `mobile` stays false on purpose: Chromium's own mobile
|
|
5
|
+
* mode adds touch events and a meta-viewport pass that Obsidian's `emulateMobile` does not expect; the override only
|
|
6
|
+
* has to make the viewport phone-sized, and `emulateMobile(true)` does the rest.
|
|
7
|
+
*/
|
|
8
|
+
export function deviceMetrics(options = {}) {
|
|
9
|
+
const width = options.width ?? DEFAULT_PHONE.width;
|
|
10
|
+
const height = options.height ?? DEFAULT_PHONE.height;
|
|
11
|
+
const scale = options.scale ?? DEFAULT_PHONE.scale;
|
|
12
|
+
for (const [name, value] of [["width", width], ["height", height], ["scale", scale]]) {
|
|
13
|
+
if (!Number.isFinite(value) || value <= 0) {
|
|
14
|
+
throw new Error(`mobile(): ${name} must be a positive number, got ${String(value)}.`);
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
return { width, height, deviceScaleFactor: scale, mobile: false };
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* True for the errors a page call raises because the page reloaded under it. `emulateMobile()` reloads the window,
|
|
21
|
+
* so the call that started it never returns; that is the only rejection `mobile()` and `desktop()` accept.
|
|
22
|
+
*/
|
|
23
|
+
export function isReloadRejection(error) {
|
|
24
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
25
|
+
return /execution context was destroyed|target (page, context or browser )?(has been )?closed|navigation|frame was detached/i.test(message);
|
|
26
|
+
}
|