Skip to content

Commit 470aa1a

Browse files
author
Shane Osbourne
committed
Docs support for special pages & better organisation
1 parent 8ea2678 commit 470aa1a

24 files changed

+192
-27
lines changed

‎.eslintignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,4 @@ docs/
33
lib/
44
Sources/ContentScopeScripts/dist/
55
integration-test/extension/contentScope.js
6+
packages/special-pages/pages/**/public

‎inject/android.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
/**
22
* @module Android integration
3+
* @category Content Scope Scripts Integrations
34
*/
45
/* global contentScopeFeatures */
56
import { processConfig, isGloballyDisabled } from './../src/utils'

‎inject/apple.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
/**
22
* @module Apple integration
3+
* @category Content Scope Scripts Integrations
34
*/
45
/* global contentScopeFeatures */
56

‎inject/chrome-mv3.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
/**
22
* @module Chrome MV3 integration
3+
* @category Content Scope Scripts Integrations
34
*/
45
/* global contentScopeFeatures */
56

‎inject/chrome.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
/**
22
* @module Chrome integration
3+
* @category Content Scope Scripts Integrations
34
*/
45
import { isTrackerOrigin } from '../src/trackers'
56

‎inject/integration.js

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,3 @@
1-
/**
2-
* @module Testing integration
3-
*/
4-
51
/* global contentScopeFeatures */
62
function getTopLevelURL () {
73
try {

‎inject/mozilla.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
/**
22
* @module Mozilla integration
3+
* @category Content Scope Scripts Integrations
34
*/
45
/* global contentScopeFeatures */
56
import { isTrackerOrigin } from '../src/trackers'

‎inject/windows.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
/**
22
* @module Windows integration
3+
* @category Content Scope Scripts Integrations
34
*/
45
/* global contentScopeFeatures */
56
import { processConfig, isGloballyDisabled, windowsSpecificFeatures } from './../src/utils'

‎packages/special-pages/index.js

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,31 @@
1+
/**
2+
* @module Special Pages
3+
* @category Special Pages
4+
*
5+
* @description
6+
*
7+
* A collection of HTML/CSS/JS pages that can be loaded into privileged environments, like `about: pages`
8+
*
9+
* - {@link "Example Page"}
10+
*/
111
import { join } from 'node:path'
212
import { existsSync, cpSync, rmSync } from 'node:fs'
313
const CWD = new URL('.', import.meta.url).pathname
414
const ROOT = new URL('../../', import.meta.url).pathname
515
const BUILD = join(ROOT, 'build')
616

717
export const support = {
8-
// example: ['windows']
18+
example: ['windows']
919
}
1020

1121
/** @type {{src: string, dest: string}[]} */
1222
const copyJobs = []
1323
const errors = []
1424

1525
for (const [pageName, platforms] of Object.entries(support)) {
16-
const src = join(CWD, 'pages', pageName)
26+
const src = join(CWD, 'pages', pageName, 'public')
1727
if (!existsSync(src)) {
18-
errors.push(`${src} does not exist`)
28+
errors.push(`${src} does not exist. Each page must have a 'public' directory`)
1929
continue
2030
}
2131
for (const platform of platforms) {
@@ -36,7 +46,7 @@ if (errors.length > 0) {
3646

3747
if (errors.length === 0) {
3848
for (const copyJob of copyJobs) {
39-
console.log('DRY RUN COPY: ', copyJob)
49+
console.log('COPY: ', copyJob)
4050
rmSync(copyJob.dest, { force: true, recursive: true })
4151
cpSync(copyJob.src, copyJob.dest, { force: true, recursive: true })
4252
}

‎packages/special-pages/package.json

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11
{
22
"name": "special-pages",
3+
"private": "true",
34
"version": "1.0.0",
45
"description": "A collection of HTML/CSS/JS pages that can be loaded into privileged environments, like about: pages",
56
"main": "index.js",
67
"type": "module",
78
"scripts": {
8-
"build": "node index.js",
9+
"build": "npm run build.pages; node index.js",
10+
"build.pages": "node scripts/build.js",
911
"test": "echo '✅ No tests yet'",
1012
"test.headed": "playwright test --headed",
1113
"test-int-x": "playwright test",
@@ -15,6 +17,8 @@
1517
"license": "ISC",
1618
"devDependencies": {
1719
"@playwright/test": "^1.31.2",
18-
"serve": "^14.2.0"
20+
"serve": "^14.2.0",
21+
"@duckduckgo/messaging": "*",
22+
"esbuild": "^0.17.12"
1923
}
2024
}

‎packages/special-pages/pages/example/.gitignore

Whitespace-only changes.

‎packages/special-pages/pages/example/public/generated/.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
*

‎packages/special-pages/pages/example/img/logo-horizontal.svg renamed to ‎packages/special-pages/pages/example/public/img/logo-horizontal.svg

File renamed without changes.

‎packages/special-pages/pages/example/index.html renamed to ‎packages/special-pages/pages/example/public/index.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,11 @@
66
content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
77
<meta http-equiv="X-UA-Compatible" content="ie=edge">
88
<title>Example special page</title>
9-
<link rel="stylesheet" href="./style.css">
9+
<link rel="stylesheet" href="style.css">
1010
</head>
1111
<body>
12-
<header class="header"><img src="./img/logo-horizontal.svg" class="logo" /></header>
12+
<header class="header"><img src="img/logo-horizontal.svg" class="logo" /></header>
1313
<h1 class="title">Hello world from a special page :)</h1>
14-
<script src="./script.js"></script>
14+
<script type="module" src="generated/js/index.js"></script>
1515
</body>
1616
</html>

‎packages/special-pages/pages/example/style.css renamed to ‎packages/special-pages/pages/example/public/style.css

File renamed without changes.

‎packages/special-pages/pages/example/readme.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
This is an example 'special' page. It contains a `public` folder which will be the output
2+
that native platforms will refer to

‎packages/special-pages/pages/example/script.js

Lines changed: 0 additions & 10 deletions
This file was deleted.

‎packages/special-pages/pages/example/src/index.js

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
/**
2+
* @module Example Page
3+
* @category Special Pages
4+
*
5+
* @description
6+
*
7+
* [[include:packages/special-pages/pages/example/readme.md]]
8+
*/
9+
10+
import { Messaging, WindowsMessagingConfig } from '../../../../messaging/index.js'
11+
import { ExamplePageMessages, } from './messages.js'
12+
import { Pixel, OverlayPixel, PlayPixel, PlayDoNotUse } from './pixels.js'
13+
14+
/**
15+
* An example of initialising Windows messaging
16+
*/
17+
const config = new WindowsMessagingConfig({
18+
featureName: 'ExamplePage',
19+
methods: {
20+
postMessage: (...args) => {
21+
console.log('postMessage', args)
22+
},
23+
addEventListener: (...args) => {
24+
console.log('addEventListener', args)
25+
},
26+
removeEventListener: (...args) => {
27+
console.log('removeEventListener', args)
28+
}
29+
}
30+
})
31+
32+
const messages = new Messaging(config)
33+
console.log(messages)
34+
35+
const h2 = document.createElement('h2')
36+
h2.innerText = 'This is an appended element'
37+
document.body.appendChild(h2)
38+
39+
try {
40+
// @ts-expect-error - this is deliberate to ensure tsc is checking this file
41+
document.body.appendChild('ooops!')
42+
} catch (e) {
43+
console.log('warn: Expected error')
44+
}
45+
46+
export { ExamplePageMessages, Pixel, OverlayPixel, PlayPixel, PlayDoNotUse }

‎packages/special-pages/pages/example/src/messages.js

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
export class ExamplePageMessages {
2+
/**
3+
* @param {import("@duckduckgo/messaging").Messaging} messaging
4+
* @internal
5+
*/
6+
constructor (messaging) {
7+
this.messaging = messaging
8+
}
9+
10+
requests = {
11+
/**
12+
* @returns {Promise<boolean>}
13+
*/
14+
getOptions: async () => {
15+
return this.messaging.request('hello', { world: 'here' })
16+
}
17+
}
18+
19+
notifications = {
20+
/**
21+
* @param {import("./pixels.js").Pixel} knownPixel
22+
*/
23+
sendPixel: (knownPixel) => {
24+
this.messaging.notify(knownPixel.name(), knownPixel.params())
25+
}
26+
}
27+
}

‎packages/special-pages/pages/example/src/pixels.js

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
/**
2+
* @group pixels
3+
*/
4+
export class OverlayPixel {
5+
/** @type {"overlay"} */
6+
name = 'overlay'
7+
}
8+
9+
/**
10+
* An example of a pixel that
11+
* @group pixels
12+
*/
13+
export class PlayPixel {
14+
name = 'play.use'
15+
/** @type {{remember: "0" | "1"}} */
16+
params
17+
/**
18+
* @param {object} params
19+
* @param {"0" | "1"} params.remember
20+
*/
21+
constructor (params) {
22+
this.params = params
23+
}
24+
}
25+
26+
/**
27+
* @group pixels
28+
*/
29+
export class PlayDoNotUse {
30+
name = 'play.do_not_use'
31+
/** @type {{remember: "0" | "1"}} */
32+
params
33+
/**
34+
* @param {object} params
35+
* @param {"0" | "1"} params.remember
36+
*/
37+
constructor (params) {
38+
this.params = params
39+
}
40+
}
41+
42+
export class Pixel {
43+
/**
44+
* A list of known pixels
45+
* @param {OverlayPixel | PlayPixel | PlayDoNotUse} input
46+
*/
47+
constructor (input) {
48+
/**
49+
* @internal
50+
*/
51+
this.input = input
52+
}
53+
54+
name () {
55+
return this.input.name
56+
}
57+
58+
params () {
59+
if ('params' in this.input) {
60+
return this.input.params
61+
}
62+
return {}
63+
}
64+
}

‎packages/special-pages/scripts/build.js

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
import { join } from 'node:path'
2+
import { buildSync } from 'esbuild'
3+
const CWD = new URL('..', import.meta.url).pathname
4+
5+
// build example page js
6+
const output = buildSync({
7+
entryPoints: [
8+
join(CWD, 'pages', 'example', 'src', 'index.js')
9+
],
10+
outdir: join(CWD, 'pages', 'example', 'public', 'generated', 'js'),
11+
bundle: true,
12+
format: 'esm'
13+
})

‎packages/special-pages/tests/example.spec.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import { test, expect } from '@playwright/test'
22

33
test('example special page', async ({ page }) => {
4-
await page.goto('/example/')
4+
await page.goto('/example/public/')
55

66
// Expect a title "to contain" a substring.
77
await expect(page).toHaveTitle(/Example special page/)

‎tsconfig.json

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020
"exclude": [
2121
"integration-test/pages",
2222
"integration-test/extension",
23+
"packages/special-pages/pages/**/public",
2324
"docs"
2425
]
2526
}

‎typedoc.json

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,23 @@
11
{
2-
"name": "@duckduckgo/workspaces-demo",
32
"entryPoints": [
43
"inject/android.js",
54
"inject/apple.js",
65
"inject/chrome.js",
76
"inject/chrome-mv3.js",
87
"inject/mozilla.js",
98
"inject/windows.js",
10-
"packages/*"
9+
"packages/messaging",
10+
"packages/special-pages/pages/example/src/index.js"
11+
],
12+
"categoryOrder": [
13+
"Special Pages",
14+
"Content Scope Scripts Integrations",
15+
"Other"
1116
],
1217
"out": "docs",
1318
"excludeExternals": true,
1419
"excludeInternal": true,
1520
"readme": "README.md",
16-
"categoryOrder": [],
1721
"treatWarningsAsErrors": true,
1822
"searchInComments": true,
1923
"includes": "."

0 commit comments

Comments
 (0)