Back

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
187x
 
 
 
 
 
 
 
 
 
 
 
 
 
 
317x
 
 
 
 
 
3x
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
150x
 
13x
 
3x
 
 
147x
 
 
 
 
 
 
 
 
 
57x
57x
 
 
 
/**
 * Internal dependencies
 */
import type { DateFilterOptions, DateFilterSurface } from './date-filter';
/**
 * External dependencies
 */
import type { DashboardWidget } from '@wordpress/widget-dashboard';
 
/**
 * A dashboard section, served by `GET /dashboards/{name}/sections` and read
 * through the `dashboardSection` core-data entity. The server-side registry is
 * the source of truth for which sections exist, their order, and their copy.
 */
export type DashboardSection = {
	/**
	 * Canonical namespaced identifier, e.g. `analytics/traffic`.
	 */
	id: string;
 
	/**
	 * URL-facing slug (the segment after the namespace), e.g. `traffic`.
	 * Persisted in the `?section=` search param and as the section-layout
	 * preference key.
	 */
	slug: string;
 
	/**
	 * Translated display label. Names the section's tab.
	 */
	label: string;
 
	/**
	 * Translated section heading, deliberately not the tab label. Read it through
	 * `resolveSectionHeading`. Optional for the same reason as `date_filter` below.
	 */
	title?: string | null;
 
	/**
	 * Sort order (ascending).
	 */
	order: number;
 
	/**
	 * Which date filter this section's header offers, registered per section on
	 * the server. Optional because a Simple site's public-api route may serve a
	 * payload built before this field existed; a missing value means the range surface.
	 */
	date_filter?: DateFilterSurface;
 
	/**
	 * Which optional controls this section's date filter offers. Optional for
	 * the same reason as `date_filter` above; absent means every control.
	 */
	date_filter_options?: DateFilterOptions;
 
	/**
	 * Whether the section's data only reaches WordPress.com through the analytics
	 * full sync, so it shows sync progress until that sync has finished once.
	 * Optional for the same reason as `date_filter` above; absent means no wait.
	 */
	requires_sync?: boolean;
 
	/**
	 * Bundled default widget layout, consumed by the reset action.
	 */
	default_layout: DashboardWidget[];
};
 
/**
 * Dashboard section identifier: the URL-facing `slug` of a `DashboardSection`.
 * Server-driven, so an open string.
 */
export type DashboardSectionId = string;
 
/**
 * The heading a section shows above its widgets. Sections that register no
 * heading of their own — Store today — head the section with their tab label.
 *
 * @param section - The section to head.
 * @return The heading text.
 */
export function resolveSectionHeading( section: DashboardSection ): string {
	// `||` rather than `??`: an empty string is a registrant meaning "none", and
	// heading the section with it would render an `<h2>` with no accessible name.
	return section.title || section.label;
}
 
/**
 * Whether a section's data is still waiting on the analytics full sync, so its
 * widgets show incomplete numbers.
 *
 * @param section        - The section to render.
 * @param isSyncFinished - Whether the analytics initial full sync has finished.
 * @return Whether the section is still waiting on the sync.
 */
export function isSectionAwaitingSync(
	section: DashboardSection,
	isSyncFinished: boolean
): boolean {
	return !! section.requires_sync && ! isSyncFinished;
}
 
/**
 * The Settings tab's slug. The stage renders that tab itself, after the registered sections.
 */
export const SETTINGS_SECTION = 'settings';
 
/**
 * Narrow a candidate slug to an available section, falling back to the first
 * section by order. A miss is a stale slug or a section unavailable now
 * (`?section=woocommerce` with WooCommerce off).
 *
 * @param value      - The candidate section slug (e.g. from the URL).
 * @param sections   - The available sections, in order.
 * @param stageSlugs - Slugs of the tabs the stage renders itself.
 * @return The resolved section slug, or an empty string when no sections exist.
 */
export function resolveSectionId(
	value: string | undefined,
	sections: DashboardSection[],
	stageSlugs: readonly string[] = []
): DashboardSectionId {
	if (
		value &&
		( stageSlugs.includes( value ) || sections.some( section => section.slug === value ) )
	) {
		return value;
	}
 
	return sections[ 0 ]?.slug ?? '';
}
 
/**
 * The widget types the inserter offers: those the available sections place by default.
 *
 * @param {DashboardSection[]} sections - The available sections.
 * @return The widget type names.
 */
export function getInsertableWidgetTypeNames( sections: DashboardSection[] ): Set< string > {
	return new Set(
		sections.flatMap( section => section.default_layout.map( widget => widget.type ) )
	);
}