@snaptrude/plugin-core 0.9.8 → 0.9.10

package/dist/api/program/metadata.d.ts

@@ -0,0 +1,328 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../types";
+import { ComponentHandle } from "../../handles";
+import { PluginSpreadsheetCell } from "./spreadsheet";
+/**
+ * Program metadata — the user-defined **custom columns** of the Program Data
+ * sheet and their per-space values.
+ *
+ * In program mode a **metadata header** is a custom column (e.g. "Department
+ * Code", "Occupancy", "Finish Level") added to the Program Data sheet; every
+ * space can then carry one **value** per header. This is the same store the
+ * Program tab reads and writes — values set here appear in the default Program
+ * Data sheet and in every custom sheet that shows the column, and values typed
+ * into the sheet are read back here. The store lives in the editor, so **no
+ * method in this namespace needs the Program tab open**.
+ *
+ * Headers are identified by a stable `headerId`. Values are plain cells
+ * (`string | number | boolean | null`); `null` clears a value. Departments and
+ * labels also carry metadata in the engine, but this namespace covers **spaces**
+ * (Mass/Floor components) — the per-space case plugins asked for.
+ *
+ * Reads never throw for a miss (`get` returns `null`, `list*` return `[]`).
+ * Writes are undoable and autosaved.
+ *
+ * Accessed via `snaptrude.program.metadata`.
+ */
+export declare abstract class PluginProgramMetadataApi {
+    constructor();
+    /**
+     * List the metadata headers (custom columns) of the Program Data sheet.
+     *
+     * @returns A {@linkcode PluginProgramMetadataListHeadersResult} with a
+     *   `headers` array (empty when the project has no custom columns).
+     *
+     * @examplePrompt List the custom metadata columns in program mode
+     * @examplePrompt What metadata headers does the program sheet have?
+     * @examplePrompt Show every custom column with its id
+     *
+     * # Example
+     * ```ts
+     * const { headers } = await snaptrude.program.metadata.listHeaders()
+     * for (const h of headers) console.log(h.headerId, h.name)
+     * ```
+     */
+    abstract listHeaders(): PluginApiReturn<PluginProgramMetadataListHeadersResult>;
+    /**
+     * Create a metadata header (a custom column on the Program Data sheet).
+     *
+     * Header names are unique per sheet: when a header with the same name already
+     * exists it is **reused** and returned (no duplicate column is created), so
+     * re-running a plugin is safe. The new column is appended after the sheet's
+     * existing custom columns.
+     *
+     * @param name - Column header text (non-empty).
+     * @param options - Optional `description` shown in the column's description
+     *   row.
+     * @returns The created (or reused) {@linkcode PluginProgramMetadataHeader}.
+     * @throws If `name` is blank.
+     *
+     * @examplePrompt Add a custom column called Occupancy to the program sheet
+     * @examplePrompt Create a metadata header named Department Code
+     * @examplePrompt Make a new program-mode column for Finish Level
+     *
+     * # Example
+     * ```ts
+     * const header = await snaptrude.program.metadata.createHeader("Occupancy", {
+     *   description: "People per room",
+     * })
+     * ```
+     */
+    abstract createHeader(name: string, options?: {
+        description?: string;
+    }): PluginApiReturn<PluginProgramMetadataCreateHeaderResult>;
+    /**
+     * Get one space's metadata values, keyed by header id.
+     *
+     * @param spaceId - The space (component id) to read.
+     * @returns A {@linkcode PluginProgramMetadataRecord} — `values` holds one entry
+     *   per header the space has a value for — or `null` when no space has that id.
+     *
+     * @examplePrompt Get the metadata on this space
+     * @examplePrompt Read the custom column values for space sp_12
+     * @examplePrompt What is this room's Occupancy metadata?
+     *
+     * # Example
+     * ```ts
+     * const record = await snaptrude.program.metadata.get("sp_12")
+     * if (record) console.log(record.values)
+     * ```
+     */
+    abstract get(spaceId: ComponentHandle): PluginApiReturn<PluginProgramMetadataGetResult>;
+    /**
+     * List metadata values for many spaces at once.
+     *
+     * Pass `spaceIds` to read specific spaces (unknown ids are skipped), or omit
+     * it to read every space in the project. One host round-trip regardless of
+     * the number of spaces — prefer this over calling
+     * {@linkcode PluginProgramMetadataApi.get} in a loop.
+     *
+     * @param spaceIds - Optional space ids to read; omit for all spaces.
+     * @returns A {@linkcode PluginProgramMetadataListResult} with one
+     *   {@linkcode PluginProgramMetadataRecord} per space.
+     *
+     * @performance One round-trip for any number of spaces — use this instead of a `get` loop.
+     *
+     * @examplePrompt List the metadata of every space
+     * @examplePrompt Read the custom column values for all rooms
+     * @examplePrompt Get the metadata for these three spaces in one call
+     *
+     * # Example
+     * ```ts
+     * const { records } = await snaptrude.program.metadata.list()
+     * const byId = Object.fromEntries(records.map((r) => [r.spaceId, r.values]))
+     * ```
+     */
+    abstract list(spaceIds?: ComponentHandle[]): PluginApiReturn<PluginProgramMetadataListResult>;
+    /**
+     * Update a space's metadata values (sparse).
+     *
+     * Only the headers present in `values` change; `null` clears a value. Every
+     * key must be an existing `headerId` (create columns first with
+     * {@linkcode PluginProgramMetadataApi.createHeader}). Undoable as one step.
+     *
+     * @param spaceId - The space (component id) to write.
+     * @param values - Header id → new cell value (`null` clears).
+     * @returns The space's full {@linkcode PluginProgramMetadataRecord} after the
+     *   write.
+     * @throws If the space or any header id does not exist.
+     *
+     * @examplePrompt Set the Occupancy metadata of this space to 4
+     * @examplePrompt Store a department code on the selected rooms
+     * @examplePrompt Write custom column values onto space sp_12
+     * @examplePrompt Clear the Finish Level metadata on this space
+     *
+     * # Example
+     * ```ts
+     * const header = await snaptrude.program.metadata.createHeader("Occupancy")
+     * await snaptrude.program.metadata.update("sp_12", { [header.headerId]: 4 })
+     * ```
+     */
+    abstract update(spaceId: ComponentHandle, values: Record<string, PluginSpreadsheetCell>): PluginApiReturn<PluginProgramMetadataUpdateResult>;
+    /**
+     * Update metadata values on many spaces in one undoable step.
+     *
+     * The plural of {@linkcode PluginProgramMetadataApi.update}: each item names a
+     * space and its sparse `values`. Results are in input order. Capped at 1000
+     * items per call.
+     *
+     * @param items - The spaces and the values to write on each.
+     * @returns A {@linkcode PluginProgramMetadataUpdateManyResult} with one record
+     *   per item, in input order.
+     * @throws If any space or header id does not exist (nothing is written).
+     *
+     * @performance One round-trip and one undo step for up to 1000 spaces — use this instead of an `update` loop.
+     *
+     * @examplePrompt Fill the Occupancy column for all bedrooms
+     * @examplePrompt Write metadata onto every selected space at once
+     * @examplePrompt Bulk-update custom column values
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.program.metadata.updateMany([
+     *   { spaceId: "sp_12", values: { [headerId]: 4 } },
+     *   { spaceId: "sp_13", values: { [headerId]: 2 } },
+     * ])
+     * ```
+     */
+    abstract updateMany(items: PluginProgramMetadataUpdateItem[]): PluginApiReturn<PluginProgramMetadataUpdateManyResult>;
+}
+/**
+ * A metadata header — one custom column of the Program Data sheet.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `headerId` | `string` | Stable header id (the key used in metadata `values`) |
+ * | `name` | `string` | Column header text |
+ * | `description` | `string` | Column description (`""` when none) |
+ * | `columnIndex` | `number` | Zero-based column index on the Program Data sheet |
+ */
+export declare const PluginProgramMetadataHeader: z.ZodObject<{
+    headerId: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    columnIndex: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginProgramMetadataHeader = z.infer<typeof PluginProgramMetadataHeader>;
+/**
+ * Result of {@linkcode PluginProgramMetadataApi.listHeaders}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `headers` | {@linkcode PluginProgramMetadataHeader}`[]` | Every custom column, in sheet column order |
+ */
+export declare const PluginProgramMetadataListHeadersResult: z.ZodObject<{
+    headers: z.ZodArray<z.ZodObject<{
+        headerId: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodString;
+        columnIndex: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginProgramMetadataListHeadersResult = z.infer<typeof PluginProgramMetadataListHeadersResult>;
+/**
+ * Arguments for {@linkcode PluginProgramMetadataApi.createHeader}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Column header text (non-empty) |
+ * | `description` | `string?` | Column description |
+ */
+export declare const PluginProgramMetadataCreateHeaderArgs: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginProgramMetadataCreateHeaderArgs = z.infer<typeof PluginProgramMetadataCreateHeaderArgs>;
+/** Result of {@linkcode PluginProgramMetadataApi.createHeader} — the created or reused header. */
+export declare const PluginProgramMetadataCreateHeaderResult: z.ZodObject<{
+    headerId: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    columnIndex: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginProgramMetadataCreateHeaderResult = z.infer<typeof PluginProgramMetadataCreateHeaderResult>;
+/**
+ * One space's metadata values.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spaceId` | `ComponentHandle` | The space's component id |
+ * | `values` | `Record<string, cell>` | Header id → value, one entry per header the space has a value for |
+ */
+export declare const PluginProgramMetadataRecord: z.ZodObject<{
+    spaceId: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+    values: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+}, z.core.$strip>;
+export type PluginProgramMetadataRecord = z.infer<typeof PluginProgramMetadataRecord>;
+/** Arguments for {@linkcode PluginProgramMetadataApi.get}. */
+export declare const PluginProgramMetadataGetArgs: z.ZodObject<{
+    spaceId: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+}, z.core.$strip>;
+export type PluginProgramMetadataGetArgs = z.infer<typeof PluginProgramMetadataGetArgs>;
+/** Result of {@linkcode PluginProgramMetadataApi.get} — the record, or `null` when the space does not exist. */
+export declare const PluginProgramMetadataGetResult: z.ZodNullable<z.ZodObject<{
+    spaceId: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+    values: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+}, z.core.$strip>>;
+export type PluginProgramMetadataGetResult = z.infer<typeof PluginProgramMetadataGetResult>;
+/**
+ * Arguments for {@linkcode PluginProgramMetadataApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spaceIds` | `ComponentHandle[]?` | Spaces to read; omit for every space |
+ */
+export declare const PluginProgramMetadataListArgs: z.ZodObject<{
+    spaceIds: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>>>;
+}, z.core.$strip>;
+export type PluginProgramMetadataListArgs = z.infer<typeof PluginProgramMetadataListArgs>;
+/**
+ * Result of {@linkcode PluginProgramMetadataApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `records` | {@linkcode PluginProgramMetadataRecord}`[]` | One record per space (unknown ids skipped) |
+ */
+export declare const PluginProgramMetadataListResult: z.ZodObject<{
+    records: z.ZodArray<z.ZodObject<{
+        spaceId: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+        values: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginProgramMetadataListResult = z.infer<typeof PluginProgramMetadataListResult>;
+/**
+ * Arguments for {@linkcode PluginProgramMetadataApi.update}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spaceId` | `ComponentHandle` | The space to write |
+ * | `values` | `Record<string, cell>` | Header id → new value (`null` clears); at least one entry |
+ */
+export declare const PluginProgramMetadataUpdateArgs: z.ZodObject<{
+    spaceId: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+    values: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+}, z.core.$strip>;
+export type PluginProgramMetadataUpdateArgs = z.infer<typeof PluginProgramMetadataUpdateArgs>;
+/** Result of {@linkcode PluginProgramMetadataApi.update} — the space's record after the write. */
+export declare const PluginProgramMetadataUpdateResult: z.ZodObject<{
+    spaceId: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+    values: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+}, z.core.$strip>;
+export type PluginProgramMetadataUpdateResult = z.infer<typeof PluginProgramMetadataUpdateResult>;
+/** One item of {@linkcode PluginProgramMetadataApi.updateMany} — mirrors the `update` args. */
+export declare const PluginProgramMetadataUpdateItem: z.ZodObject<{
+    spaceId: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+    values: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+}, z.core.$strip>;
+export type PluginProgramMetadataUpdateItem = z.infer<typeof PluginProgramMetadataUpdateItem>;
+/** Maximum items per {@linkcode PluginProgramMetadataApi.updateMany} call. */
+export declare const PLUGIN_PROGRAM_METADATA_BATCH_LIMIT = 1000;
+/**
+ * Arguments for {@linkcode PluginProgramMetadataApi.updateMany}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `items` | {@linkcode PluginProgramMetadataUpdateItem}`[]` | 1–1000 space updates |
+ */
+export declare const PluginProgramMetadataUpdateManyArgs: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        spaceId: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+        values: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginProgramMetadataUpdateManyArgs = z.infer<typeof PluginProgramMetadataUpdateManyArgs>;
+/**
+ * Result of {@linkcode PluginProgramMetadataApi.updateMany}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `records` | {@linkcode PluginProgramMetadataRecord}`[]` | One record per item, in input order |
+ */
+export declare const PluginProgramMetadataUpdateManyResult: z.ZodObject<{
+    records: z.ZodArray<z.ZodObject<{
+        spaceId: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+        values: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginProgramMetadataUpdateManyResult = z.infer<typeof PluginProgramMetadataUpdateManyResult>;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/api/program/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../../src/api/program/metadata.ts"],"names":[],"mappings":"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"}

package/dist/api/program/spreadsheet.d.ts

@@ -752,6 +752,129 @@ export declare abstract class PluginProgramSpreadsheetApi {
      * ```
      */
     abstract ping(): PluginApiReturn<PluginProgramSpreadsheetPingResult>;
+    /**
+     * Create a **custom program sheet** — a live view of the program grouped by a
+     * configurable hierarchy (the Program tab's "Custom" sheet with *Organize →
+     * Group by*).
+     *
+     * Unlike {@linkcode PluginProgramSpreadsheetApi.createSheet} (a blank sheet you
+     * write cells into), a custom sheet is data-bound: its rows are the project's
+     * spaces, re-rendered from the model, grouped by `groupBy` in order (e.g.
+     * `["departmentName", "<metadataHeaderId>", "label"]` for a healthcare
+     * department → sub-department → room hierarchy) and showing the `properties`
+     * columns. Valid property ids come from
+     * {@linkcode PluginProgramSpreadsheetApi.listCustomSheetProperties} — built-in
+     * properties plus every program metadata header id. The configuration is
+     * saved with the sheet.
+     *
+     * @param name - The sheet name to create (must not already exist).
+     * @param options - Optional `groupBy` (property ids, outermost first; default
+     *   none), `properties` (column property ids, in order; default
+     *   `["label", "areas"]`), and `groupColors` (property id → CSS hex fill for
+     *   that level's group headers).
+     * @returns The sheet's {@linkcode PluginSpreadsheetCustomSheet} configuration.
+     * @throws If a sheet named `name` already exists, or a property id is unknown.
+     *
+     * @examplePrompt Create a custom sheet grouped by department then sub-department
+     * @examplePrompt Make a program view grouped by storey and label
+     * @examplePrompt Build a grouped program sheet for the healthcare hierarchy
+     * @examplePrompt Add a custom sheet with a department → room type group-by
+     *
+     * # Example
+     * ```ts
+     * const { headers } = await snaptrude.program.metadata.listHeaders()
+     * const subDept = headers.find((h) => h.name === "Sub-department")
+     * await snaptrude.program.spreadsheet.createCustomSheet("Clinical Program", {
+     *   groupBy: ["departmentName", subDept.headerId, "label"],
+     *   properties: ["label", "count", "areas", "netAreaAchieved"],
+     * })
+     * ```
+     */
+    abstract createCustomSheet(name: string, options?: {
+        groupBy?: string[];
+        properties?: string[];
+        groupColors?: Record<string, string>;
+    }): PluginApiReturn<PluginProgramSpreadsheetCustomSheetResult>;
+    /**
+     * Update a custom program sheet's group-by hierarchy, columns, or group colors.
+     *
+     * A **sparse** update: omitted fields are left unchanged. The sheet is
+     * re-rendered once and the configuration saved.
+     *
+     * @param sheetName - The custom sheet to update.
+     * @param options - Any of `groupBy`, `properties`, `groupColors` (see
+     *   {@linkcode PluginProgramSpreadsheetApi.createCustomSheet}).
+     * @returns The sheet's updated {@linkcode PluginSpreadsheetCustomSheet}.
+     * @throws If `sheetName` is not a custom program sheet, or a property id is
+     *   unknown.
+     *
+     * @examplePrompt Change the custom sheet to group by storey first
+     * @examplePrompt Add the Occupancy column to my grouped program sheet
+     * @examplePrompt Regroup the Clinical Program sheet by department only
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.program.spreadsheet.updateCustomSheet("Clinical Program", {
+     *   groupBy: ["storey", "departmentName"],
+     * })
+     * ```
+     */
+    abstract updateCustomSheet(sheetName: string, options: {
+        groupBy?: string[];
+        properties?: string[];
+        groupColors?: Record<string, string>;
+    }): PluginApiReturn<PluginProgramSpreadsheetCustomSheetResult>;
+    /**
+     * Get a custom program sheet's configuration.
+     *
+     * @param sheetName - The sheet to read.
+     * @returns Its {@linkcode PluginSpreadsheetCustomSheet}, or `null` when no
+     *   custom program sheet has that name (plain sheets return `null` too).
+     *
+     * @examplePrompt How is the Clinical Program sheet grouped?
+     * @examplePrompt Get the group-by configuration of this custom sheet
+     *
+     * # Example
+     * ```ts
+     * const cfg = await snaptrude.program.spreadsheet.getCustomSheet("Clinical Program")
+     * if (cfg) console.log(cfg.groupBy, cfg.properties)
+     * ```
+     */
+    abstract getCustomSheet(sheetName: string): PluginApiReturn<PluginProgramSpreadsheetGetCustomSheetResult>;
+    /**
+     * List the custom program sheets in the workbook with their configurations.
+     *
+     * @returns A {@linkcode PluginProgramSpreadsheetListCustomSheetsResult} with a
+     *   `sheets` array (empty when there are none).
+     *
+     * @examplePrompt List the custom program sheets
+     * @examplePrompt Which sheets are grouped program views?
+     *
+     * # Example
+     * ```ts
+     * const { sheets } = await snaptrude.program.spreadsheet.listCustomSheets()
+     * ```
+     */
+    abstract listCustomSheets(): PluginApiReturn<PluginProgramSpreadsheetListCustomSheetsResult>;
+    /**
+     * List the property ids a custom program sheet can show as columns or group by.
+     *
+     * Built-in properties (`label`, `departmentName`, `storey`, `areas`, …) plus
+     * one entry per program metadata header (its `headerId`). `groupable` is
+     * `false` for computed properties that can only be columns.
+     *
+     * @returns A {@linkcode PluginProgramSpreadsheetListCustomSheetPropertiesResult}.
+     *
+     * @examplePrompt What can I group a custom program sheet by?
+     * @examplePrompt List the columns available for a custom sheet
+     *
+     * # Example
+     * ```ts
+     * const { properties } = await snaptrude.program.spreadsheet.listCustomSheetProperties()
+     * const groupable = properties.filter((p) => p.groupable).map((p) => p.id)
+     * ```
+     */
+    abstract listCustomSheetProperties(): PluginApiReturn<PluginProgramSpreadsheetListCustomSheetPropertiesResult>;
 }
 /**
  * Program-spreadsheet templates — capture a sheet's layout as a named, reusable
@@ -2362,4 +2485,144 @@ export declare const PluginProgramSpreadsheetAddImageResult: z.ZodObject<{
     name: z.ZodString;
 }, z.core.$strip>;
 export type PluginProgramSpreadsheetAddImageResult = z.infer<typeof PluginProgramSpreadsheetAddImageResult>;
+/**
+ * A custom program sheet's configuration — the grouped, data-bound program view
+ * created by {@linkcode PluginProgramSpreadsheetApi.createCustomSheet}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string` | The sheet's name |
+ * | `groupBy` | `string[]` | Group-by hierarchy, outermost first (property ids); `[]` when ungrouped |
+ * | `properties` | `string[]` | Column property ids in column order (`""` marks an unassigned column) |
+ * | `groupColors` | `Record<string, string>` | Property id → CSS hex fill of that level's group headers |
+ * | `proposalId` | `string \| null` | The proposal the sheet belongs to, or `null` when the project has none |
+ */
+export declare const PluginSpreadsheetCustomSheet: z.ZodObject<{
+    sheetName: z.ZodString;
+    groupBy: z.ZodArray<z.ZodString>;
+    properties: z.ZodArray<z.ZodString>;
+    groupColors: z.ZodRecord<z.ZodString, z.ZodString>;
+    proposalId: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type PluginSpreadsheetCustomSheet = z.infer<typeof PluginSpreadsheetCustomSheet>;
+/**
+ * The configurable part of a custom program sheet, for
+ * {@linkcode PluginProgramSpreadsheetApi.createCustomSheet} /
+ * {@linkcode PluginProgramSpreadsheetApi.updateCustomSheet}. All fields optional.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `groupBy` | `string[]?` | Group-by hierarchy, outermost first (property ids) |
+ * | `properties` | `string[]?` | Column property ids, in order |
+ * | `groupColors` | `Record<string, string>?` | Property id → CSS hex fill for that level's group headers |
+ */
+export declare const PluginSpreadsheetCustomSheetConfig: z.ZodObject<{
+    groupBy: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    properties: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    groupColors: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+export type PluginSpreadsheetCustomSheetConfig = z.infer<typeof PluginSpreadsheetCustomSheetConfig>;
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetApi.createCustomSheet}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | The sheet name to create |
+ * | `groupBy` / `properties` / `groupColors` | — | See {@linkcode PluginSpreadsheetCustomSheetConfig} |
+ */
+export declare const PluginProgramSpreadsheetCreateCustomSheetArgs: z.ZodObject<{
+    groupBy: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    properties: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    groupColors: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    name: z.ZodString;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetCreateCustomSheetArgs = z.infer<typeof PluginProgramSpreadsheetCreateCustomSheetArgs>;
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetApi.updateCustomSheet}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string` | The custom sheet to update |
+ * | `groupBy` / `properties` / `groupColors` | — | Sparse; see {@linkcode PluginSpreadsheetCustomSheetConfig} |
+ */
+export declare const PluginProgramSpreadsheetUpdateCustomSheetArgs: z.ZodObject<{
+    groupBy: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    properties: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    groupColors: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    sheetName: z.ZodString;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetUpdateCustomSheetArgs = z.infer<typeof PluginProgramSpreadsheetUpdateCustomSheetArgs>;
+/** Result of `createCustomSheet` / `updateCustomSheet` — the sheet's configuration. */
+export declare const PluginProgramSpreadsheetCustomSheetResult: z.ZodObject<{
+    sheetName: z.ZodString;
+    groupBy: z.ZodArray<z.ZodString>;
+    properties: z.ZodArray<z.ZodString>;
+    groupColors: z.ZodRecord<z.ZodString, z.ZodString>;
+    proposalId: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetCustomSheetResult = z.infer<typeof PluginProgramSpreadsheetCustomSheetResult>;
+/** Arguments for {@linkcode PluginProgramSpreadsheetApi.getCustomSheet}. */
+export declare const PluginProgramSpreadsheetGetCustomSheetArgs: z.ZodObject<{
+    sheetName: z.ZodString;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetGetCustomSheetArgs = z.infer<typeof PluginProgramSpreadsheetGetCustomSheetArgs>;
+/** Result of {@linkcode PluginProgramSpreadsheetApi.getCustomSheet} — the configuration, or `null`. */
+export declare const PluginProgramSpreadsheetGetCustomSheetResult: z.ZodNullable<z.ZodObject<{
+    sheetName: z.ZodString;
+    groupBy: z.ZodArray<z.ZodString>;
+    properties: z.ZodArray<z.ZodString>;
+    groupColors: z.ZodRecord<z.ZodString, z.ZodString>;
+    proposalId: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>>;
+export type PluginProgramSpreadsheetGetCustomSheetResult = z.infer<typeof PluginProgramSpreadsheetGetCustomSheetResult>;
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.listCustomSheets}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheets` | {@linkcode PluginSpreadsheetCustomSheet}`[]` | Every custom program sheet |
+ */
+export declare const PluginProgramSpreadsheetListCustomSheetsResult: z.ZodObject<{
+    sheets: z.ZodArray<z.ZodObject<{
+        sheetName: z.ZodString;
+        groupBy: z.ZodArray<z.ZodString>;
+        properties: z.ZodArray<z.ZodString>;
+        groupColors: z.ZodRecord<z.ZodString, z.ZodString>;
+        proposalId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetListCustomSheetsResult = z.infer<typeof PluginProgramSpreadsheetListCustomSheetsResult>;
+/**
+ * A property a custom program sheet can show or group by.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Property id (built-in key, or a metadata `headerId`) |
+ * | `name` | `string` | Display name |
+ * | `groupable` | `boolean` | Whether the sheet can group by it |
+ * | `custom` | `boolean` | `true` for program metadata headers, `false` for built-ins |
+ */
+export declare const PluginSpreadsheetCustomSheetProperty: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    groupable: z.ZodBoolean;
+    custom: z.ZodBoolean;
+}, z.core.$strip>;
+export type PluginSpreadsheetCustomSheetProperty = z.infer<typeof PluginSpreadsheetCustomSheetProperty>;
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.listCustomSheetProperties}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `properties` | {@linkcode PluginSpreadsheetCustomSheetProperty}`[]` | Built-ins first, then metadata headers |
+ */
+export declare const PluginProgramSpreadsheetListCustomSheetPropertiesResult: z.ZodObject<{
+    properties: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        groupable: z.ZodBoolean;
+        custom: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginProgramSpreadsheetListCustomSheetPropertiesResult = z.infer<typeof PluginProgramSpreadsheetListCustomSheetPropertiesResult>;
 //# sourceMappingURL=spreadsheet.d.ts.map