1
/*
2
 * types.ts
3
 *
4
 * Copyright (C) 2020-2022 Posit Software, PBC
5
 */
6

7
import { RenderServices } from "../command/render/types.ts";
8
import { Metadata, PandocFlags } from "../config/types.ts";
9
import { Format, FormatExtras } from "../config/types.ts";
10
import {
11
  Brand,
12
  LightDarkBrand,
13
  LightDarkBrandDarkFlag,
14
} from "../core/brand/brand.ts";
15
import { MappedString } from "../core/mapped-text.ts";
16
import { PartitionedMarkdown } from "../core/pandoc/types.ts";
17
import {
18
  ExecutionEngineDiscovery,
19
  ExecutionEngineInstance,
20
  ExecutionTarget,
21
} from "../execute/types.ts";
22
import { InspectedMdCell } from "../inspect/inspect-types.ts";
23
import { NotebookContext } from "../render/notebook/notebook-types.ts";
24
import {
25
  LogoLightDarkSpecifier,
26
  NavigationItem as NavItem,
27
  NavigationItemObject,
28
  NavigationItemObject as SidebarTool,
29
  ProjectConfig as ProjectConfig_Project,
30
} from "../resources/types/schema-types.ts";
31
import { ProjectEnvironment } from "./project-environment-types.ts";
32
import { ProjectCache } from "../core/cache/cache-types.ts";
33
import { TempContext } from "../core/temp-types.ts";
34
import { Cloneable } from "../core/safe-clone-deep.ts";
35

36
export {
37
  type NavigationItem as NavItem,
38
  type NavigationItemObject,
39
  type NavigationItemObject as SidebarTool,
40
  type PageFooter as NavigationFooter,
41
  type ProjectPreview,
42
} from "../resources/types/schema-types.ts";
43

44
export const kProjectType = "type";
45
export const kProjectTitle = "title";
46
export const kProjectRender = "render";
47
export const kProjectPreRender = "pre-render";
48
export const kProjectPostRender = "post-render";
49
export const kProjectExecuteDir = "execute-dir";
50
export const kProjectOutputDir = "output-dir";
51
export const kProjectLibDir = "lib-dir";
52
export const kProjectResources = "resources";
53

54
export const kProjectWatchInputs = "watch-inputs";
55

56
export type FileInclusion = {
57
  source: string;
58
  target: string;
59
};
60

61
export type FileInformation = {
62
  fullMarkdown?: MappedString;
63
  includeMap?: FileInclusion[];
64
  codeCells?: InspectedMdCell[];
65
  engine?: ExecutionEngineInstance;
66
  target?: ExecutionTarget;
67
  metadata?: Metadata;
68
  brand?: LightDarkBrandDarkFlag;
69
};
70

71
export interface FileInformationCache extends Map<string, FileInformation> {
72
  // Removes a cache entry and cleans up any associated transient files from disk.
73
  // Use this instead of delete() when invalidating entries that may reference
74
  // transient notebooks (.quarto_ipynb) to prevent file accumulation.
75
  invalidateForFile(key: string): void;
76
}
77

78
export interface ProjectContext extends Cloneable<ProjectContext> {
79
  dir: string;
80
  engines: string[];
81
  files: ProjectFiles;
82
  config?: ProjectConfig;
83
  notebookContext: NotebookContext;
84
  outputNameIndex?: Map<string, { file: string; format: Format } | undefined>;
85

86
  fileInformationCache: FileInformationCache;
87

88
  // This is a cache of _brand.yml for a project
89
  brandCache?: { brand?: LightDarkBrandDarkFlag };
90
  resolveBrand: (
91
    fileName?: string,
92
  ) => Promise<
93
    undefined | LightDarkBrandDarkFlag
94
  >;
95

96
  // expands markdown for a file
97
  // input file doesn't have to be markdown; it can be, for example, a knitr spin file
98
  // output file is always markdown, though, and it is cached in the project
99

100
  resolveFullMarkdownForFile: (
101
    engine: ExecutionEngineInstance | undefined,
102
    file: string,
103
    markdown?: MappedString,
104
    force?: boolean,
105
  ) => Promise<MappedString>;
106

107
  fileExecutionEngineAndTarget: (
108
    file: string,
109
    force?: boolean,
110
  ) => Promise<{ engine: ExecutionEngineInstance; target: ExecutionTarget }>;
111

112
  fileMetadata: (
113
    file: string,
114
    force?: boolean,
115
  ) => Promise<Metadata>;
116

117
  formatExtras?: (
118
    source: string,
119
    flags: PandocFlags,
120
    format: Format,
121
    services: RenderServices,
122
  ) => Promise<FormatExtras>;
123

124
  // declaring renderFormats here is a relatively ugly hack to avoid a circular import chain
125
  // that causes a deno bundler bug
126
  renderFormats: (
127
    file: string,
128
    services: RenderServices,
129
    to: string | undefined,
130
    project: ProjectContext,
131
  ) => Promise<Record<string, Format>>;
132

133
  environment: () => Promise<ProjectEnvironment>;
134

135
  isSingleFile: boolean;
136
  previewServer?: boolean;
137

138
  diskCache: ProjectCache;
139
  temp: TempContext;
140

141
  cleanup: () => void;
142
}
143

144
export interface ProjectFiles {
145
  input: string[];
146
  resources?: string[];
147
  config?: string[];
148
  configResources?: string[];
149
}
150

151
export interface ProjectConfig {
152
  project: ProjectConfig_Project;
153
  [key: string]: unknown;
154
}
155

156
export const kProject404File = "404.html";
157

158
export type LayoutBreak = "" | "sm" | "md" | "lg" | "xl" | "xxl";
159

160
/**
161
 * A restricted version of ProjectContext that only exposes
162
 * functionality needed by execution engines.
163
 */
164
export interface EngineProjectContext {
165
  /**
166
   * Base directory of the project
167
   */
168
  dir: string;
169

170
  /**
171
   * Flag indicating if project consists of a single file
172
   */
173
  isSingleFile: boolean;
174

175
  /**
176
   * Config object containing project configuration
177
   * Used primarily for config?.engines access
178
   * Can contain arbitrary configuration properties
179
   */
180
  config?: {
181
    engines?: string[];
182
    project?: {
183
      [kProjectOutputDir]?: string;
184
    };
185
    [key: string]: unknown;
186
  };
187

188
  /**
189
   * For file information cache management
190
   * Used for the transient notebook tracking in Jupyter
191
   */
192
  fileInformationCache: FileInformationCache;
193

194
  /**
195
   * Get the output directory for the project
196
   *
197
   * @returns Path to output directory
198
   */
199
  getOutputDirectory: () => string;
200

201
  /**
202
   * Resolves full markdown content for a file, including expanding includes
203
   *
204
   * @param engine - The execution engine
205
   * @param file - Path to the file
206
   * @param markdown - Optional existing markdown content
207
   * @param force - Whether to force re-resolution even if cached
208
   * @returns Promise resolving to mapped markdown string
209
   */
210
  resolveFullMarkdownForFile: (
211
    engine: ExecutionEngineInstance | undefined,
212
    file: string,
213
    markdown?: MappedString,
214
    force?: boolean,
215
  ) => Promise<MappedString>;
216
}
217

218
export const kAriaLabel = "aria-label";
219
export const kCollapseLevel = "collapse-level";
220
export const kCollapseBelow = "collapse-below";
221
export const kToolsCollapse = "tools-collapse";
222
export const kLogoAlt = "logo-alt";
223
export const kLogoHref = "logo-href";
224

225
export const kSidebarMenus = "sidebar-menus";
226

227
export interface Navbar {
228
  title?: string | false;
229
  logo?: LogoLightDarkSpecifier;
230
  [kLogoAlt]?: string;
231
  [kLogoHref]?: string;
232
  background:
233
    | "primary"
234
    | "secondary"
235
    | "success"
236
    | "danger"
237
    | "warning"
238
    | "info"
239
    | "light"
240
    | "dark";
241
  search?: boolean | string;
242
  left?: NavItem[];
243
  right?: NavItem[];
244
  collapse?: boolean;
245
  tools?: SidebarTool[];
246
  pinned?: boolean;
247
  [kCollapseBelow]?: LayoutBreak;
248
  [kSidebarMenus]?: boolean;
249
  darkToggle?: boolean;
250
  readerToggle?: boolean;
251
  [kToolsCollapse]?: boolean;
252
}
253

254
/* export interface NavItem {
255
  // href + more readable/understndable aliases
256
  icon?: string;
257
  href?: string;
258
  file?: string;
259
  text?: string;
260
  url?: string;
261
  [kAriaLabel]?: string;
262

263
  // core identification
264
  id?: string;
265

266
  // more
267
  menu?: NavItem[];
268
}
269
 */
270

271
export interface Sidebar {
272
  id?: string;
273
  title?: string;
274
  subtitle?: string;
275
  logo?: LogoLightDarkSpecifier;
276
  [kLogoAlt]?: string;
277
  [kLogoHref]?: string;
278
  alignment?: "left" | "right" | "center";
279
  align?: "left" | "right" | "center"; // This is here only because older versions of Quarto used to use it even though it wasn't documented
280
  background?:
281
    | "none"
282
    | "primary"
283
    | "secondary"
284
    | "success"
285
    | "danger"
286
    | "warning"
287
    | "info"
288
    | "light"
289
    | "dark"
290
    | "white";
291
  search?: boolean | string;
292
  [kCollapseLevel]?: number;
293
  contents: SidebarItem[];
294
  tools: SidebarTool[];
295
  style: "docked" | "floating";
296
  pinned?: boolean;
297
  header?: Array<string> | string;
298
  footer?: Array<string> | string;
299
}
300

301
export type SidebarItem = NavigationItemObject & {
302
  // core structure/contents
303
  section?: string;
304
  sectionId?: string;
305
  contents?: SidebarItem[];
306

307
  // more
308
  expanded?: boolean;
309
  active?: boolean;
310

311
  // transient properties used for expanding 'auto'
312
  auto?: boolean | string | string[];
313
};
314

315
export interface InputTargetIndex extends Metadata {
316
  title?: string;
317
  markdown: PartitionedMarkdown;
318
  formats: Record<string, Format>;
319
  draft?: boolean;
320
}
321

322
export interface InputTarget {
323
  input: string;
324
  title?: string;
325
  outputHref: string;
326
  draft: boolean;
327
}
328

329
/*export interface SidebarTool {
330
  // label/contents
331
  icon?: string;
332
  text?: string;
333
  menu?: NavItem[];
334

335
  // href + more readable/understndable aliases
336
  href?: string;
337
  file?: string;
338
  url?: string;
339
}*/
340

341