@wix/site-service-pages 1.5.0 → 1.7.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.
Files changed (7) hide show
  1. package/README.md +1 -1
  2. package/cjs/build/definition/index.d.ts +44 -54
  3. package/cjs/build/definition/index.js.map +1 -1
  4. package/dist/definition/index.d.ts +44 -54
  5. package/dist/definition/index.js.map +1 -1
  6. package/package.json +4 -4
  7. package/src/definition/index.ts +44 -54
package/README.md CHANGED
@@ -5,7 +5,7 @@ Provides all site pages (with popup flag), the current page, and the main page.
5
5
  ## Install
6
6
 
7
7
  ```sh
8
- yarn add @wix/site-service-pages
8
+ pnpm add @wix/site-service-pages
9
9
  ```
10
10
 
11
11
  ## Usage
package/cjs/build/definition/index.d.ts CHANGED
@@ -1,33 +1,32 @@
1
1
  import type { ServiceDefinition } from '@wix/services-definitions';
2
2
  /**
3
- * A page on a site, without its ID.
3
+ * A page on a site, as it appears in the `pages` map.
4
4
  *
5
- * This is the value type of the `pages` map, where the map key is the page ID.
5
+ * It has no `id` property. The page's ID is its key in the `pages` map.
6
6
  */
7
7
  export type PageConfig = {
8
8
  /**
9
- * Page title, as a Wix user set it in the editor. This is the text shown in
10
- * site navigation menus.
9
+ * Page title, as a Wix user named the page in the editor.
11
10
  *
12
- * @exampleValue 'Shop'
11
+ * @exampleValue 'Spring Collection'
13
12
  */
14
13
  title: string;
15
14
  /**
16
- * Page path, as the host supplies it.
15
+ * Page path, relative to the site root URL.
17
16
  *
18
- * The service stores the value unchanged and doesn't normalize it, so
19
- * don't assume a leading slash. Join it to a base URL rather than
20
- * concatenating, for example with the standard
21
- * [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) object.
17
+ * For a nested page, the path usually starts with its parent page's path, such as `collections/spring`.
18
+ * When a Wix user turns off URL hierarchy in the site's SEO settings, the path is just the page's own
19
+ * slug, such as `spring`. To find a page's parent, use `parentPageId`, not the path.
22
20
  *
23
- * @exampleValue 'shop'
21
+ * To build the page's URL, join the site root URL and the path with a single `/`.
22
+ *
23
+ * @exampleValue 'collections/spring'
24
24
  */
25
25
  path: string;
26
26
  /**
27
- * ID of the page that this page sits under in the site's navigation.
27
+ * ID of this page's parent page in the site's page structure.
28
28
  *
29
- * Available only for a page nested under another page. A top-level page has
30
- * no parent. The value is a key in the `pages` map.
29
+ * Undefined if the page doesn't have a parent page.
31
30
  *
32
31
  * @exampleValue 'i9xk2'
33
32
  */
@@ -35,40 +34,29 @@ export type PageConfig = {
35
34
  /**
36
35
  * Whether the page is a popup.
37
36
  *
38
- * A popup opens over the page a visitor is already on rather than replacing
39
- * it. Popups appear in the `pages` map alongside ordinary pages, so filter on
40
- * this property to get only ordinary pages, or only popups.
37
+ * The `pages` map includes popups, so filter on this value before building links or navigation.
41
38
  *
42
39
  * @exampleValue false
43
40
  */
44
41
  popup: boolean;
45
42
  /**
46
- * ID of the section that this page provides in the app that owns it, such as a
47
- * Wix Stores product page or a Wix Bookings checkout page.
43
+ * ID of the app section this page provides.
48
44
  *
49
- * This value is unique in an app but not across apps, so pair it with
50
- * `appDefinitionId` to identify a page.
45
+ * The ID stays the same across sites, even though a Wix user can change the page's path. It's unique
46
+ * only within its app, so another installed app can use the same ID.
51
47
  *
52
- * Available only for a page belonging to an installed app.
48
+ * Available only for a page that belongs to an installed app.
53
49
  *
54
50
  * @exampleValue 'ecom_side_cart'
55
51
  */
56
52
  appPageId?: string;
57
- /**
58
- * ID of the app that owns this page. This is the app's `appDefinitionId`,
59
- * which you can find in your app's dashboard. For an app created by Wix, see
60
- * [Apps Created by Wix](https://dev.wix.com/docs/rest/articles/getting-started/apps-created-by-wix).
61
- *
62
- * Available only for a page belonging to an installed app.
63
- *
64
- * @exampleValue '1380b703-ce81-ff05-f115-39571d94dfcd'
65
- */
53
+ /** @internal Not documented: the host doesn't populate it yet (host PR #48632 set only `appPageId`). */
66
54
  appDefinitionId?: string;
67
55
  };
68
56
  /** A page on a site, including its ID. */
69
57
  export type Page = PageConfig & {
70
58
  /**
71
- * Page ID. This is the page's key in the `pages` map.
59
+ * Page ID.
72
60
  *
73
61
  * @exampleValue 'c1dmp'
74
62
  */
@@ -76,50 +64,52 @@ export type Page = PageConfig & {
76
64
  };
77
65
  /** Values the host supplies when it creates the service. */
78
66
  export type IPagesServiceConfig = {
79
- /** id-as-key map; values omit `id` — callers use the key as the id (P3). */
67
+ /** Every page on the site, keyed by page ID. The values have no `id`. */
80
68
  pages: {
81
69
  [pageId: string]: PageConfig;
82
70
  };
83
- /** Provider resolves and passes the full main page object; service stores it as-is. */
71
+ /** The main page. The service stores it unchanged. */
84
72
  mainPage: Page;
85
- /** Provider resolves and passes the full current page object; service stores it as-is. */
73
+ /** The page that's currently displayed. The service stores it unchanged. */
86
74
  currentPage: Page;
87
75
  };
88
76
  /**
89
- * Provides the pages of a Wix site: every page the site has, the page a visitor
90
- * is currently on, and the page a visitor reaches at the site root.
91
- *
92
- * Use it to build navigation, to read the title or path of the current page, and
93
- * to find a page belonging to an installed Wix app.
94
- *
95
- * The service only provides values. It doesn't create or change pages, and it
96
- * doesn't navigate a visitor between them.
77
+ * Provides every page on a Wix site, the page that's currently displayed, and the main page to code
78
+ * running on the site.
97
79
  */
98
80
  export interface IPagesService {
99
81
  /**
100
- * Every page on a site, keyed by page ID.
82
+ * Every page on the site, keyed by page ID.
83
+ *
84
+ * The values don't include an `id`. Use the key as the page's ID.
101
85
  *
102
- * The values in this map don't carry an `id` property. The key is the page's
103
- * ID, so read it from the key or from the entry's position in the map.
86
+ * Don't change the map or its pages. The property is read-only, but the map it returns isn't, and
87
+ * every component on the page shares it.
104
88
  *
105
- * The map includes popups, which each page's `popup` property flags.
89
+ * @exampleValue `{ "m4rw8": { "title": "Home", "path": "home", "popup": false }, "c1dmp": { "title": "Shop", "path": "shop", "popup": false }, "i9xk2": { "title": "Collections", "path": "collections", "popup": false }, "t5nb6": { "title": "Spring Collection", "path": "collections/spring", "parentPageId": "i9xk2", "popup": false }, "q7hz3": { "title": "Side Cart", "path": "side-cart", "popup": true, "appPageId": "ecom_side_cart" } }`
106
90
  */
107
91
  readonly pages: {
108
92
  [pageId: string]: PageConfig;
109
93
  };
110
94
  /**
111
- * The page a visitor reaches at the site root.
95
+ * Main page, the page a site visitor reaches at the site root URL.
96
+ *
97
+ * A Wix user chooses which page this is. To check whether the page that's currently displayed is the
98
+ * main page, compare `currentPage.id` with `mainPage.id`.
112
99
  *
113
- * This is the page a Wix user set as the site's home page, which isn't
114
- * necessarily the first page in `pages`.
100
+ * Don't change its fields. The property is read-only, but the object it returns isn't, and every
101
+ * component on the page shares it.
102
+ *
103
+ * @exampleValue `{ "id": "m4rw8", "title": "Home", "path": "home", "popup": false }`
115
104
  */
116
105
  readonly mainPage: Page;
117
106
  /**
118
- * The page a visitor is currently on.
107
+ * Page that's currently displayed.
108
+ *
109
+ * Don't change its fields. The property is read-only, but the object it returns isn't, and every
110
+ * component on the page shares it.
119
111
  *
120
- * The host decides which page this is and the service stores it
121
- * unchanged, so a popup can appear here. Check the page's `popup`
122
- * property when that distinction matters.
112
+ * @exampleValue `{ "id": "c1dmp", "title": "Shop", "path": "shop", "popup": false }`
123
113
  */
124
114
  readonly currentPage: Page;
125
115
  /** @internal Host-only. Replaces config values when the host's state changes. */
package/cjs/build/definition/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/definition/index.ts"],"names":[],"mappings":";;;AAAA,oEAAyD;AAsI5C,QAAA,eAAe,GAAG,IAAA,oCAAa,EAAqC,yBAAyB,CAAC,CAAA"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/definition/index.ts"],"names":[],"mappings":";;;AAAA,oEAAyD;AA4H5C,QAAA,eAAe,GAAG,IAAA,oCAAa,EAAqC,yBAAyB,CAAC,CAAA"}
package/dist/definition/index.d.ts CHANGED
@@ -1,33 +1,32 @@
1
1
  import type { ServiceDefinition } from '@wix/services-definitions';
2
2
  /**
3
- * A page on a site, without its ID.
3
+ * A page on a site, as it appears in the `pages` map.
4
4
  *
5
- * This is the value type of the `pages` map, where the map key is the page ID.
5
+ * It has no `id` property. The page's ID is its key in the `pages` map.
6
6
  */
7
7
  export type PageConfig = {
8
8
  /**
9
- * Page title, as a Wix user set it in the editor. This is the text shown in
10
- * site navigation menus.
9
+ * Page title, as a Wix user named the page in the editor.
11
10
  *
12
- * @exampleValue 'Shop'
11
+ * @exampleValue 'Spring Collection'
13
12
  */
14
13
  title: string;
15
14
  /**
16
- * Page path, as the host supplies it.
15
+ * Page path, relative to the site root URL.
17
16
  *
18
- * The service stores the value unchanged and doesn't normalize it, so
19
- * don't assume a leading slash. Join it to a base URL rather than
20
- * concatenating, for example with the standard
21
- * [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) object.
17
+ * For a nested page, the path usually starts with its parent page's path, such as `collections/spring`.
18
+ * When a Wix user turns off URL hierarchy in the site's SEO settings, the path is just the page's own
19
+ * slug, such as `spring`. To find a page's parent, use `parentPageId`, not the path.
22
20
  *
23
- * @exampleValue 'shop'
21
+ * To build the page's URL, join the site root URL and the path with a single `/`.
22
+ *
23
+ * @exampleValue 'collections/spring'
24
24
  */
25
25
  path: string;
26
26
  /**
27
- * ID of the page that this page sits under in the site's navigation.
27
+ * ID of this page's parent page in the site's page structure.
28
28
  *
29
- * Available only for a page nested under another page. A top-level page has
30
- * no parent. The value is a key in the `pages` map.
29
+ * Undefined if the page doesn't have a parent page.
31
30
  *
32
31
  * @exampleValue 'i9xk2'
33
32
  */
@@ -35,40 +34,29 @@ export type PageConfig = {
35
34
  /**
36
35
  * Whether the page is a popup.
37
36
  *
38
- * A popup opens over the page a visitor is already on rather than replacing
39
- * it. Popups appear in the `pages` map alongside ordinary pages, so filter on
40
- * this property to get only ordinary pages, or only popups.
37
+ * The `pages` map includes popups, so filter on this value before building links or navigation.
41
38
  *
42
39
  * @exampleValue false
43
40
  */
44
41
  popup: boolean;
45
42
  /**
46
- * ID of the section that this page provides in the app that owns it, such as a
47
- * Wix Stores product page or a Wix Bookings checkout page.
43
+ * ID of the app section this page provides.
48
44
  *
49
- * This value is unique in an app but not across apps, so pair it with
50
- * `appDefinitionId` to identify a page.
45
+ * The ID stays the same across sites, even though a Wix user can change the page's path. It's unique
46
+ * only within its app, so another installed app can use the same ID.
51
47
  *
52
- * Available only for a page belonging to an installed app.
48
+ * Available only for a page that belongs to an installed app.
53
49
  *
54
50
  * @exampleValue 'ecom_side_cart'
55
51
  */
56
52
  appPageId?: string;
57
- /**
58
- * ID of the app that owns this page. This is the app's `appDefinitionId`,
59
- * which you can find in your app's dashboard. For an app created by Wix, see
60
- * [Apps Created by Wix](https://dev.wix.com/docs/rest/articles/getting-started/apps-created-by-wix).
61
- *
62
- * Available only for a page belonging to an installed app.
63
- *
64
- * @exampleValue '1380b703-ce81-ff05-f115-39571d94dfcd'
65
- */
53
+ /** @internal Not documented: the host doesn't populate it yet (host PR #48632 set only `appPageId`). */
66
54
  appDefinitionId?: string;
67
55
  };
68
56
  /** A page on a site, including its ID. */
69
57
  export type Page = PageConfig & {
70
58
  /**
71
- * Page ID. This is the page's key in the `pages` map.
59
+ * Page ID.
72
60
  *
73
61
  * @exampleValue 'c1dmp'
74
62
  */
@@ -76,50 +64,52 @@ export type Page = PageConfig & {
76
64
  };
77
65
  /** Values the host supplies when it creates the service. */
78
66
  export type IPagesServiceConfig = {
79
- /** id-as-key map; values omit `id` — callers use the key as the id (P3). */
67
+ /** Every page on the site, keyed by page ID. The values have no `id`. */
80
68
  pages: {
81
69
  [pageId: string]: PageConfig;
82
70
  };
83
- /** Provider resolves and passes the full main page object; service stores it as-is. */
71
+ /** The main page. The service stores it unchanged. */
84
72
  mainPage: Page;
85
- /** Provider resolves and passes the full current page object; service stores it as-is. */
73
+ /** The page that's currently displayed. The service stores it unchanged. */
86
74
  currentPage: Page;
87
75
  };
88
76
  /**
89
- * Provides the pages of a Wix site: every page the site has, the page a visitor
90
- * is currently on, and the page a visitor reaches at the site root.
91
- *
92
- * Use it to build navigation, to read the title or path of the current page, and
93
- * to find a page belonging to an installed Wix app.
94
- *
95
- * The service only provides values. It doesn't create or change pages, and it
96
- * doesn't navigate a visitor between them.
77
+ * Provides every page on a Wix site, the page that's currently displayed, and the main page to code
78
+ * running on the site.
97
79
  */
98
80
  export interface IPagesService {
99
81
  /**
100
- * Every page on a site, keyed by page ID.
82
+ * Every page on the site, keyed by page ID.
83
+ *
84
+ * The values don't include an `id`. Use the key as the page's ID.
101
85
  *
102
- * The values in this map don't carry an `id` property. The key is the page's
103
- * ID, so read it from the key or from the entry's position in the map.
86
+ * Don't change the map or its pages. The property is read-only, but the map it returns isn't, and
87
+ * every component on the page shares it.
104
88
  *
105
- * The map includes popups, which each page's `popup` property flags.
89
+ * @exampleValue `{ "m4rw8": { "title": "Home", "path": "home", "popup": false }, "c1dmp": { "title": "Shop", "path": "shop", "popup": false }, "i9xk2": { "title": "Collections", "path": "collections", "popup": false }, "t5nb6": { "title": "Spring Collection", "path": "collections/spring", "parentPageId": "i9xk2", "popup": false }, "q7hz3": { "title": "Side Cart", "path": "side-cart", "popup": true, "appPageId": "ecom_side_cart" } }`
106
90
  */
107
91
  readonly pages: {
108
92
  [pageId: string]: PageConfig;
109
93
  };
110
94
  /**
111
- * The page a visitor reaches at the site root.
95
+ * Main page, the page a site visitor reaches at the site root URL.
96
+ *
97
+ * A Wix user chooses which page this is. To check whether the page that's currently displayed is the
98
+ * main page, compare `currentPage.id` with `mainPage.id`.
112
99
  *
113
- * This is the page a Wix user set as the site's home page, which isn't
114
- * necessarily the first page in `pages`.
100
+ * Don't change its fields. The property is read-only, but the object it returns isn't, and every
101
+ * component on the page shares it.
102
+ *
103
+ * @exampleValue `{ "id": "m4rw8", "title": "Home", "path": "home", "popup": false }`
115
104
  */
116
105
  readonly mainPage: Page;
117
106
  /**
118
- * The page a visitor is currently on.
107
+ * Page that's currently displayed.
108
+ *
109
+ * Don't change its fields. The property is read-only, but the object it returns isn't, and every
110
+ * component on the page shares it.
119
111
  *
120
- * The host decides which page this is and the service stores it
121
- * unchanged, so a popup can appear here. Check the page's `popup`
122
- * property when that distinction matters.
112
+ * @exampleValue `{ "id": "c1dmp", "title": "Shop", "path": "shop", "popup": false }`
123
113
  */
124
114
  readonly currentPage: Page;
125
115
  /** @internal Host-only. Replaces config values when the host's state changes. */
package/dist/definition/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/definition/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAsIzD,MAAM,CAAC,MAAM,eAAe,GAAG,aAAa,CAAqC,yBAAyB,CAAC,CAAA"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/definition/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AA4HzD,MAAM,CAAC,MAAM,eAAe,GAAG,aAAa,CAAqC,yBAAyB,CAAC,CAAA"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wix/site-service-pages",
3
- "version": "1.5.0",
3
+ "version": "1.7.0",
4
4
  "license": "UNLICENSED",
5
5
  "files": [
6
6
  "dist",
@@ -48,8 +48,8 @@
48
48
  },
49
49
  "scripts": {
50
50
  "build": "tsc -b . && tsc --project tsconfig.cjs.json",
51
- "lint": "yarn run -T lint:package $npm_package_name",
52
- "test": "vitest --run && yarn test-type-check",
51
+ "lint": "pnpm --workspace-root run lint:package --package $npm_package_name",
52
+ "test": "vitest --run && pnpm run test-type-check",
53
53
  "test-type-check": "echo 'validating typescript in test files' && tsc --project tsconfig.test.json && echo 'Finished validating typescript in test files successfully'"
54
54
  },
55
55
  "dependencies": {
@@ -77,5 +77,5 @@
77
77
  ]
78
78
  }
79
79
  },
80
- "falconPackageHash": "ad192fc40720e725d6745fc6e25b6368849f4a2f93aa002f6c0de021"
80
+ "falconPackageHash": "824488b92b2bde49e25e9c1f378ddd32847adfd2b0da037d3d25865f"
81
81
  }
package/src/definition/index.ts CHANGED
@@ -2,34 +2,33 @@ import { defineService } from '@wix/services-definitions'
2
2
  import type { ServiceDefinition } from '@wix/services-definitions'
3
3
 
4
4
  /**
5
- * A page on a site, without its ID.
5
+ * A page on a site, as it appears in the `pages` map.
6
6
  *
7
- * This is the value type of the `pages` map, where the map key is the page ID.
7
+ * It has no `id` property. The page's ID is its key in the `pages` map.
8
8
  */
9
9
  export type PageConfig = {
10
10
  /**
11
- * Page title, as a Wix user set it in the editor. This is the text shown in
12
- * site navigation menus.
11
+ * Page title, as a Wix user named the page in the editor.
13
12
  *
14
- * @exampleValue 'Shop'
13
+ * @exampleValue 'Spring Collection'
15
14
  */
16
15
  title: string
17
16
  /**
18
- * Page path, as the host supplies it.
17
+ * Page path, relative to the site root URL.
19
18
  *
20
- * The service stores the value unchanged and doesn't normalize it, so
21
- * don't assume a leading slash. Join it to a base URL rather than
22
- * concatenating, for example with the standard
23
- * [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) object.
19
+ * For a nested page, the path usually starts with its parent page's path, such as `collections/spring`.
20
+ * When a Wix user turns off URL hierarchy in the site's SEO settings, the path is just the page's own
21
+ * slug, such as `spring`. To find a page's parent, use `parentPageId`, not the path.
24
22
  *
25
- * @exampleValue 'shop'
23
+ * To build the page's URL, join the site root URL and the path with a single `/`.
24
+ *
25
+ * @exampleValue 'collections/spring'
26
26
  */
27
27
  path: string
28
28
  /**
29
- * ID of the page that this page sits under in the site's navigation.
29
+ * ID of this page's parent page in the site's page structure.
30
30
  *
31
- * Available only for a page nested under another page. A top-level page has
32
- * no parent. The value is a key in the `pages` map.
31
+ * Undefined if the page doesn't have a parent page.
33
32
  *
34
33
  * @exampleValue 'i9xk2'
35
34
  */
@@ -37,41 +36,30 @@ export type PageConfig = {
37
36
  /**
38
37
  * Whether the page is a popup.
39
38
  *
40
- * A popup opens over the page a visitor is already on rather than replacing
41
- * it. Popups appear in the `pages` map alongside ordinary pages, so filter on
42
- * this property to get only ordinary pages, or only popups.
39
+ * The `pages` map includes popups, so filter on this value before building links or navigation.
43
40
  *
44
41
  * @exampleValue false
45
42
  */
46
43
  popup: boolean
47
44
  /**
48
- * ID of the section that this page provides in the app that owns it, such as a
49
- * Wix Stores product page or a Wix Bookings checkout page.
45
+ * ID of the app section this page provides.
50
46
  *
51
- * This value is unique in an app but not across apps, so pair it with
52
- * `appDefinitionId` to identify a page.
47
+ * The ID stays the same across sites, even though a Wix user can change the page's path. It's unique
48
+ * only within its app, so another installed app can use the same ID.
53
49
  *
54
- * Available only for a page belonging to an installed app.
50
+ * Available only for a page that belongs to an installed app.
55
51
  *
56
52
  * @exampleValue 'ecom_side_cart'
57
53
  */
58
54
  appPageId?: string
59
- /**
60
- * ID of the app that owns this page. This is the app's `appDefinitionId`,
61
- * which you can find in your app's dashboard. For an app created by Wix, see
62
- * [Apps Created by Wix](https://dev.wix.com/docs/rest/articles/getting-started/apps-created-by-wix).
63
- *
64
- * Available only for a page belonging to an installed app.
65
- *
66
- * @exampleValue '1380b703-ce81-ff05-f115-39571d94dfcd'
67
- */
55
+ /** @internal Not documented: the host doesn't populate it yet (host PR #48632 set only `appPageId`). */
68
56
  appDefinitionId?: string
69
57
  }
70
58
 
71
59
  /** A page on a site, including its ID. */
72
60
  export type Page = PageConfig & {
73
61
  /**
74
- * Page ID. This is the page's key in the `pages` map.
62
+ * Page ID.
75
63
  *
76
64
  * @exampleValue 'c1dmp'
77
65
  */
@@ -80,49 +68,51 @@ export type Page = PageConfig & {
80
68
 
81
69
  /** Values the host supplies when it creates the service. */
82
70
  export type IPagesServiceConfig = {
83
- /** id-as-key map; values omit `id` — callers use the key as the id (P3). */
71
+ /** Every page on the site, keyed by page ID. The values have no `id`. */
84
72
  pages: { [pageId: string]: PageConfig }
85
- /** Provider resolves and passes the full main page object; service stores it as-is. */
73
+ /** The main page. The service stores it unchanged. */
86
74
  mainPage: Page
87
- /** Provider resolves and passes the full current page object; service stores it as-is. */
75
+ /** The page that's currently displayed. The service stores it unchanged. */
88
76
  currentPage: Page
89
77
  }
90
78
 
91
79
  /**
92
- * Provides the pages of a Wix site: every page the site has, the page a visitor
93
- * is currently on, and the page a visitor reaches at the site root.
94
- *
95
- * Use it to build navigation, to read the title or path of the current page, and
96
- * to find a page belonging to an installed Wix app.
97
- *
98
- * The service only provides values. It doesn't create or change pages, and it
99
- * doesn't navigate a visitor between them.
80
+ * Provides every page on a Wix site, the page that's currently displayed, and the main page to code
81
+ * running on the site.
100
82
  */
101
83
  export interface IPagesService {
102
84
  /**
103
- * Every page on a site, keyed by page ID.
85
+ * Every page on the site, keyed by page ID.
86
+ *
87
+ * The values don't include an `id`. Use the key as the page's ID.
104
88
  *
105
- * The values in this map don't carry an `id` property. The key is the page's
106
- * ID, so read it from the key or from the entry's position in the map.
89
+ * Don't change the map or its pages. The property is read-only, but the map it returns isn't, and
90
+ * every component on the page shares it.
107
91
  *
108
- * The map includes popups, which each page's `popup` property flags.
92
+ * @exampleValue `{ "m4rw8": { "title": "Home", "path": "home", "popup": false }, "c1dmp": { "title": "Shop", "path": "shop", "popup": false }, "i9xk2": { "title": "Collections", "path": "collections", "popup": false }, "t5nb6": { "title": "Spring Collection", "path": "collections/spring", "parentPageId": "i9xk2", "popup": false }, "q7hz3": { "title": "Side Cart", "path": "side-cart", "popup": true, "appPageId": "ecom_side_cart" } }`
109
93
  */
110
94
  readonly pages: { [pageId: string]: PageConfig }
111
95
 
112
96
  /**
113
- * The page a visitor reaches at the site root.
97
+ * Main page, the page a site visitor reaches at the site root URL.
98
+ *
99
+ * A Wix user chooses which page this is. To check whether the page that's currently displayed is the
100
+ * main page, compare `currentPage.id` with `mainPage.id`.
114
101
  *
115
- * This is the page a Wix user set as the site's home page, which isn't
116
- * necessarily the first page in `pages`.
102
+ * Don't change its fields. The property is read-only, but the object it returns isn't, and every
103
+ * component on the page shares it.
104
+ *
105
+ * @exampleValue `{ "id": "m4rw8", "title": "Home", "path": "home", "popup": false }`
117
106
  */
118
107
  readonly mainPage: Page
119
108
 
120
109
  /**
121
- * The page a visitor is currently on.
110
+ * Page that's currently displayed.
111
+ *
112
+ * Don't change its fields. The property is read-only, but the object it returns isn't, and every
113
+ * component on the page shares it.
122
114
  *
123
- * The host decides which page this is and the service stores it
124
- * unchanged, so a popup can appear here. Check the page's `popup`
125
- * property when that distinction matters.
115
+ * @exampleValue `{ "id": "c1dmp", "title": "Shop", "path": "shop", "popup": false }`
126
116
  */
127
117
  readonly currentPage: Page
128
118