Generated
Vendored
+274
@@ -0,0 +1,274 @@
|
||||
# Presentation Quick Start (TypeScript)
|
||||
|
||||
## API Docs
|
||||
|
||||
API docs: `api/API_DOCS.md`
|
||||
|
||||
`Presentation` is the in-memory API object. A deck is the exported presentation
|
||||
file. A slide is one page in the deck.
|
||||
|
||||
## Imports
|
||||
|
||||
```ts
|
||||
import fs from "node:fs/promises";
|
||||
import { FileBlob, Presentation, PresentationFile } from "@oai/artifact-tool";
|
||||
```
|
||||
|
||||
## Create, Render, Export
|
||||
|
||||
This script creates an editable deck, renders each slide PNG, and exports PPTX.
|
||||
|
||||
```ts
|
||||
import fs from "node:fs/promises";
|
||||
import { Presentation, PresentationFile } from "@oai/artifact-tool";
|
||||
|
||||
async function writeBlob(path: string, blob: Blob): Promise<void> {
|
||||
await fs.writeFile(path, new Uint8Array(await blob.arrayBuffer()));
|
||||
}
|
||||
|
||||
async function main(): Promise<void> {
|
||||
await fs.mkdir("output", { recursive: true });
|
||||
|
||||
const presentation = Presentation.create({
|
||||
slideSize: { width: 1280, height: 720 },
|
||||
});
|
||||
|
||||
const slide = presentation.slides.add();
|
||||
slide.background.fill = "slate-50";
|
||||
|
||||
const page = { left: 72, top: 64, width: 1136, height: 592 };
|
||||
const gutter = 28;
|
||||
const leftCol = 430;
|
||||
const rightCol = page.width - leftCol - gutter;
|
||||
|
||||
const eyebrow = slide.shapes.add({
|
||||
geometry: "textbox",
|
||||
position: { left: page.left, top: page.top, width: 280, height: 28 },
|
||||
fill: "none",
|
||||
line: { style: "solid", fill: "none", width: 0 },
|
||||
});
|
||||
eyebrow.text = "EDITABLE PRESENTATION";
|
||||
eyebrow.text.style = { fontSize: 12, bold: true, color: "slate-500" };
|
||||
|
||||
const title = slide.shapes.add({
|
||||
geometry: "textbox",
|
||||
position: {
|
||||
left: page.left,
|
||||
top: page.top + 92,
|
||||
width: leftCol,
|
||||
height: 184,
|
||||
},
|
||||
fill: "none",
|
||||
line: { style: "solid", fill: "none", width: 0 },
|
||||
});
|
||||
title.text = "Build decks with editable objects";
|
||||
title.text.style = { fontSize: 42, bold: true, color: "slate-950" };
|
||||
|
||||
const subtitle = slide.shapes.add({
|
||||
geometry: "textbox",
|
||||
position: {
|
||||
left: page.left,
|
||||
top: page.top + 292,
|
||||
width: leftCol,
|
||||
height: 96,
|
||||
},
|
||||
fill: "none",
|
||||
line: { style: "solid", fill: "none", width: 0 },
|
||||
});
|
||||
subtitle.text =
|
||||
"Rows, columns, grids, charts, tables, images, and text remain editable.";
|
||||
subtitle.text.style = { fontSize: 20, color: "slate-600" };
|
||||
|
||||
const chartFrame = slide.shapes.add({
|
||||
geometry: "roundRect",
|
||||
name: "chart-frame",
|
||||
position: {
|
||||
left: page.left + leftCol + gutter,
|
||||
top: page.top + 92,
|
||||
width: rightCol,
|
||||
height: 388,
|
||||
},
|
||||
fill: "white",
|
||||
line: { style: "solid", fill: "slate-200", width: 1 },
|
||||
borderRadius: "rounded-2xl",
|
||||
shadow: "shadow-sm",
|
||||
});
|
||||
|
||||
slide.charts.add("bar", {
|
||||
position: {
|
||||
left: chartFrame.position.left + 36,
|
||||
top: chartFrame.position.top + 52,
|
||||
width: chartFrame.position.width - 72,
|
||||
height: 280,
|
||||
},
|
||||
categories: ["Rows", "Grid", "Tokens"],
|
||||
series: [{ name: "Coverage", values: [3, 4, 5], fill: "accent1" }],
|
||||
hasLegend: false,
|
||||
dataLabels: { showValue: true, position: "outEnd" },
|
||||
yAxis: {
|
||||
majorGridlines: { style: "solid", fill: "slate-200", width: 1 },
|
||||
},
|
||||
});
|
||||
|
||||
for (const [index, slide] of presentation.slides.items.entries()) {
|
||||
const stem = `slide-${String(index + 1).padStart(2, "0")}`;
|
||||
const png = await presentation.export({ slide, format: "png", scale: 1 });
|
||||
await writeBlob(`output/${stem}.png`, png);
|
||||
}
|
||||
|
||||
const pptx = await PresentationFile.exportPptx(presentation);
|
||||
await pptx.save("output/deck.pptx");
|
||||
}
|
||||
|
||||
main().catch((error) => {
|
||||
console.error(error);
|
||||
process.exitCode = 1;
|
||||
});
|
||||
```
|
||||
|
||||
Inspect every final slide at full size before delivery. After repairs, refresh
|
||||
the affected slide previews, including slides affected by inherited changes.
|
||||
Add the [optional inspection exports](#optional-inspection-exports) when needed.
|
||||
|
||||
## JSX Compose Equivalent
|
||||
|
||||
Use JSX when the slide is naturally rows, columns, grids, or overlays.
|
||||
|
||||
```tsx
|
||||
/** @jsxRuntime automatic */
|
||||
/** @jsxImportSource @oai/artifact-tool/presentation-jsx */
|
||||
|
||||
const frame = { left: 72, top: 64, width: 1136, height: 592 };
|
||||
|
||||
slide.compose(
|
||||
<column name="content-frame" width="fill" height="fill" gap={28}>
|
||||
<row width="fill" height={72} align="center" justify="between">
|
||||
<paragraph name="eyebrow" className="text-slate-500 text-sm font-bold">
|
||||
EDITABLE PRESENTATION
|
||||
</paragraph>
|
||||
<paragraph className="text-slate-400 text-sm">Q2 planning</paragraph>
|
||||
</row>
|
||||
<row width="fill" height="fill" gap={28} align="stretch">
|
||||
<column width={430} height="fill" gap={18}>
|
||||
<paragraph
|
||||
name="primary-heading"
|
||||
className="text-slate-950 text-5xl font-bold leading-tight"
|
||||
>
|
||||
Build decks with editable objects
|
||||
</paragraph>
|
||||
<paragraph className="text-slate-600 text-xl leading-relaxed">
|
||||
Rows, columns, grids, charts, tables, images, and text remain
|
||||
editable.
|
||||
</paragraph>
|
||||
</column>
|
||||
<box
|
||||
name="chart-frame"
|
||||
width="fill"
|
||||
height="fill"
|
||||
className="bg-white rounded-2xl shadow-sm"
|
||||
line={{ style: "solid", fill: "slate-200", width: 1 }}
|
||||
>
|
||||
<chart
|
||||
name="coverage-chart"
|
||||
chartType="bar"
|
||||
categories={["Rows", "Grid", "Tokens"]}
|
||||
series={[{ name: "Coverage", values: [3, 4, 5], fill: "accent1" }]}
|
||||
hasLegend={false}
|
||||
width="fill"
|
||||
height="fill"
|
||||
/>
|
||||
</box>
|
||||
</row>
|
||||
</column>,
|
||||
{ frame, baseUnit: 8 },
|
||||
);
|
||||
```
|
||||
|
||||
## Import And Edit PPTX
|
||||
|
||||
Load a PPTX, inspect for stable ids, render the affected slide before and after
|
||||
a focused edit, re-inspect, and export the edited PPTX.
|
||||
|
||||
```ts
|
||||
const presentation = await PresentationFile.importPptx(
|
||||
await FileBlob.load("input.pptx"),
|
||||
);
|
||||
|
||||
const before = await presentation.inspect({
|
||||
kind: "slide,textbox,shape,image,table,chart,notes,thread,layout",
|
||||
search: "Revenue",
|
||||
maxChars: 8000,
|
||||
});
|
||||
console.log(before.ndjson);
|
||||
|
||||
const slide = presentation.resolve(slideIdFromInspect);
|
||||
await writeBlob(
|
||||
"output/before-slide.png",
|
||||
await presentation.export({ slide, format: "png", scale: 1 }),
|
||||
);
|
||||
|
||||
const target = presentation.resolve(anchorIdFromInspect);
|
||||
target.text.replace("Revenue", "Updated revenue outlook");
|
||||
|
||||
await writeBlob(
|
||||
"output/after-slide.png",
|
||||
await presentation.export({ slide, format: "png", scale: 1 }),
|
||||
);
|
||||
|
||||
const after = await presentation.inspect({
|
||||
target: { id: anchorIdFromInspect, beforeLines: 2, afterLines: 2 },
|
||||
kind: "textbox,shape,image,table,chart",
|
||||
maxChars: 3000,
|
||||
});
|
||||
console.log(after.ndjson);
|
||||
|
||||
const pptx = await PresentationFile.exportPptx(presentation);
|
||||
await pptx.save("output/edited-deck.pptx");
|
||||
```
|
||||
|
||||
## Optional Inspection Exports
|
||||
|
||||
When investigating placement, export layout evidence for the affected slide
|
||||
in the authoring process. Capture it before and after a change when comparison
|
||||
is useful.
|
||||
|
||||
```ts
|
||||
const layout = await slide.export({ format: "layout" });
|
||||
await fs.writeFile("output/slide.layout.json", await layout.text());
|
||||
```
|
||||
|
||||
For deck flow or changes affecting multiple slides, add an overview montage.
|
||||
Continue to inspect individual slide PNGs at full size.
|
||||
|
||||
```ts
|
||||
const montage = await presentation.export({
|
||||
format: "webp",
|
||||
montage: true,
|
||||
});
|
||||
await writeBlob("output/deck-montage.webp", montage);
|
||||
```
|
||||
|
||||
## Local Image Bytes
|
||||
|
||||
Use byte-backed images for embedded PPTX assets.
|
||||
|
||||
```ts
|
||||
async function readImageBlob(imagePath: string): Promise<ArrayBuffer> {
|
||||
const bytes = await fs.readFile(imagePath);
|
||||
return bytes.buffer.slice(
|
||||
bytes.byteOffset,
|
||||
bytes.byteOffset + bytes.byteLength,
|
||||
);
|
||||
}
|
||||
|
||||
const imageBytes = await readImageBlob("assets/product.png");
|
||||
slide.images.add({
|
||||
blob: imageBytes,
|
||||
contentType: "image/png",
|
||||
alt: "Product screenshot",
|
||||
fit: "cover",
|
||||
position: { left: 720, top: 96, width: 420, height: 280 },
|
||||
geometry: "roundRect",
|
||||
borderRadius: "rounded-xl",
|
||||
});
|
||||
```
|
||||
Generated
Vendored
+270
@@ -0,0 +1,270 @@
|
||||
# Presentation API Docs
|
||||
|
||||
Use the presentation facades to create PowerPoint-style decks in TypeScript.
|
||||
|
||||
## Conventions (units + presets)
|
||||
|
||||
- **Pixels everywhere**: all slide geometry uses CSS pixels (`px`) at 96 DPI: `position.{left,top,width,height}`, line widths, and text `fontSize`.
|
||||
- **Default canvas for examples**: use `1280 x 720` unless the task or source deck says otherwise. A useful full-slide content frame is `{ left: 72, top: 64, width: 1136, height: 592 }`.
|
||||
- **Angles**: rotations use degrees.
|
||||
- **Preset geometry**: `geometry` uses preset shape-name strings. Use standard shape presets and `geometry: "custom"` for bespoke paths.
|
||||
- **Gradients**: stop `offset` ranges from `0` to `100000`.
|
||||
- **Config-first authoring**: pass config objects into create/add APIs and grouped setters when the API provides them.
|
||||
- **String values**: options such as geometry, fit, alignment, chart type, line style, and connector kind are strings; reference pages list exact small unions and grep targets for huge catalogs.
|
||||
- **Inline docs types**: reference pages include illustrative `type ... = { ... }` blocks. Treat them as schema-shaped authoring guidance, not imports.
|
||||
- **Authoring surfaces**: `slide.compose(...)` covers rows, columns, grids, layers, and token strings. Config-first facade APIs cover exact positions, fixed chrome, native charts/tables/images, and imported deck edits.
|
||||
|
||||
## Common Routes
|
||||
|
||||
- Rows, columns, grids, overlays, and 12-column spans: [`references/cookbook/layout.md`](./references/cookbook/layout.md).
|
||||
- JSX node props and sizing mechanics: [`references/jsx.md`](./references/jsx.md).
|
||||
- Tailwind-like visual strings: [`references/tokens.md`](./references/tokens.md).
|
||||
- Inspect, resolve, edit, preview, and re-inspect loops: [`references/cookbook/imported-deck.md`](./references/cookbook/imported-deck.md).
|
||||
|
||||
## Quick start
|
||||
|
||||
```ts
|
||||
const presentation = Presentation.create({
|
||||
slideSize: { width: 1280, height: 720 },
|
||||
});
|
||||
|
||||
const slide = presentation.slides.add();
|
||||
slide.background.fill = "slate-50";
|
||||
|
||||
const headline = slide.shapes.add({
|
||||
geometry: "textbox",
|
||||
name: "headline",
|
||||
position: { left: 72, top: 64, width: 720, height: 96 },
|
||||
fill: "none",
|
||||
line: { style: "solid", fill: "none", width: 0 },
|
||||
});
|
||||
headline.text = "Editable headline";
|
||||
headline.text.style = { fontSize: 44, bold: true, color: "slate-950" };
|
||||
|
||||
const shape = slide.shapes.add({
|
||||
geometry: "roundRect",
|
||||
name: "summary-surface",
|
||||
position: { left: 72, top: 188, width: 520, height: 300 },
|
||||
fill: "white",
|
||||
line: { style: "solid", fill: "slate-200", width: 1 },
|
||||
borderRadius: "rounded-2xl",
|
||||
});
|
||||
|
||||
const previewBlob = await presentation.export({
|
||||
slide,
|
||||
format: "png",
|
||||
scale: 2,
|
||||
});
|
||||
const deckPdfBlob = await presentation.export({ format: "pdf" });
|
||||
const slidePdfBlob = await presentation.export({ slide, format: "pdf" });
|
||||
const snapshot = await presentation.inspect({
|
||||
kind: "slide,textbox,shape",
|
||||
maxChars: 4000,
|
||||
});
|
||||
const help = presentation.help("*", {
|
||||
search: "chart axis labels",
|
||||
include: ["index", "notes"],
|
||||
maxChars: 4000,
|
||||
});
|
||||
const proto = presentation.toProto();
|
||||
```
|
||||
|
||||
Inspect every final slide PNG at full size. After repairs, refresh previews for
|
||||
the affected slides, including those affected by inherited changes.
|
||||
|
||||
## Optional Inspection Exports
|
||||
|
||||
When investigating placement, export layout evidence for the affected slide:
|
||||
|
||||
```ts
|
||||
const layoutBlob = await slide.export({ format: "layout" });
|
||||
```
|
||||
|
||||
For deck flow or changes affecting multiple slides, export an overview montage:
|
||||
|
||||
```ts
|
||||
const montageBlob = await presentation.export({
|
||||
format: "webp",
|
||||
montage: true,
|
||||
});
|
||||
```
|
||||
|
||||
Capture these before and after edits when comparison is useful. A montage
|
||||
supports deck-level review; use individual PNGs for full-size slide inspection.
|
||||
|
||||
## Load Existing Presentation Data
|
||||
|
||||
Load a PPTX from a local path:
|
||||
|
||||
```ts
|
||||
const presentation = await Presentation.load("input.pptx");
|
||||
```
|
||||
|
||||
Load serialized presentation data with `Presentation.load(proto)`:
|
||||
|
||||
```ts
|
||||
const presentation = Presentation.load(proto);
|
||||
|
||||
const before = await presentation.inspect({
|
||||
kind: "slide,textbox,shape,image,table,chart,notes,thread,layout",
|
||||
search: "Revenue",
|
||||
maxChars: 8000,
|
||||
});
|
||||
|
||||
const slide = presentation.resolve(slideAnchorIdFromInspect);
|
||||
const previewBefore = await presentation.export({
|
||||
slide,
|
||||
format: "png",
|
||||
scale: 1,
|
||||
});
|
||||
|
||||
const target = presentation.resolve(anchorIdFromInspect);
|
||||
target.text.replace("Revenue", "Revenue outlook");
|
||||
target.text.style = { fontSize: 24, color: "slate-950", bold: true };
|
||||
|
||||
const previewAfter = await presentation.export({
|
||||
slide,
|
||||
format: "png",
|
||||
scale: 1,
|
||||
});
|
||||
const after = await presentation.inspect({
|
||||
target: { id: anchorIdFromInspect, beforeLines: 2, afterLines: 2 },
|
||||
kind: "textbox,shape,image,table,chart",
|
||||
maxChars: 3000,
|
||||
});
|
||||
const nextProto = presentation.toProto();
|
||||
```
|
||||
|
||||
## Compose-first layout
|
||||
|
||||
```tsx
|
||||
/** @jsxRuntime automatic */
|
||||
|
||||
const presentation = Presentation.create();
|
||||
const slide = presentation.slides.add();
|
||||
|
||||
slide.compose(
|
||||
<column width="fill" height="fill" gap={16}>
|
||||
<paragraph
|
||||
name="headline"
|
||||
className="text-slate-950 text-3xl leading-tight"
|
||||
>
|
||||
<run textStyle={{ bold: true }}>Quarterly</run>
|
||||
<run> readiness</run>
|
||||
</paragraph>
|
||||
<rule stroke="#0f172a" width={160} weight={2} />
|
||||
</column>,
|
||||
{
|
||||
frame: { left: 48, top: 40, width: 864, height: 460 },
|
||||
baseUnit: 8,
|
||||
},
|
||||
);
|
||||
```
|
||||
|
||||
Use `name` for stable inspect and layout-export targeting. JSX materializing
|
||||
tags default `width` to `"fill"` when you omit it.
|
||||
|
||||
## Core API Sequence
|
||||
|
||||
- Create presentations with `Presentation.create({ slideSize })` to control default slide dimensions.
|
||||
- Add slides with `presentation.slides.add({ layout, layoutId })` or `presentation.slides.insert({ after, ... })`.
|
||||
- Use `slide.compose(nodeOrJsx, { frame, baseUnit })` for compose-first layouts. JSX lowers into the same compose runtime as the helper-based API.
|
||||
- Author content with config-first calls: `slide.shapes.add({ geometry, position, fill, line })`, `slide.images.add({ ... })`, `slide.tables.add({ ... })`, and `slide.charts.add(chartType, { ... })`.
|
||||
- Format whole-shape text with grouped configs such as `shape.text.style = { fontSize, bold, color, alignment }`.
|
||||
- Edit imported decks with `presentation.inspect({ kind, search, maxChars })`, `presentation.resolve(anchorId)`, and focused facade edits.
|
||||
- Export previews with `presentation.export({ slide, format, scale })`.
|
||||
- Export all slides as one PDF with `presentation.export({ format: "pdf" })`.
|
||||
- Export deck montages for overview review with `presentation.export({ format: "webp", montage: true })`.
|
||||
- Export layout JSON for placement investigations with `slide.export({ format: "layout" })`.
|
||||
- Control editor gridlines and imported guides with `presentation.view`.
|
||||
- Search API help with `presentation.help(query, { search, include, maxChars })`.
|
||||
- Run high-level edits with `presentation.scripts.run(kind, options)`; see [`references/presentation.spec.md`](./references/presentation.spec.md) for the script surface.
|
||||
|
||||
## Output Map
|
||||
|
||||
| Output | API | Result |
|
||||
| ------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------ |
|
||||
| All slide previews | `presentation.render()` | PNG blobs in deck order, named `slide-1.png`, `slide-2.png`, and so on |
|
||||
| Selected previews | `presentation.render({ slide: [0, 2] })` | PNG blobs for zero-based indexes, in requested order |
|
||||
| Raster preview | `presentation.render({ slide, format: "png", scale })` | One raster blob for a `Slide` or a single zero-based index |
|
||||
| Slide PNG | `presentation.export({ slide, format: "png", scale })` | One preview image for one slide |
|
||||
| Deck PDF | `presentation.export({ format: "pdf" })` | One PDF `Blob` with one page per slide |
|
||||
| Slide PDF | `presentation.export({ slide, format: "pdf" })` | One PDF `Blob` for one slide |
|
||||
| Editable PPTX | `presentation.export({ format: "pptx" })` | Editable presentation `Blob` |
|
||||
| Deck montage | `presentation.export({ format: "webp", montage: true, scale })` | One overview image containing the deck slides |
|
||||
| Layout JSON | `slide.export({ format: "layout" })` | Structural JSON with bounds, ids, text, names, and object metadata |
|
||||
| Searchable snapshot | `presentation.inspect({ kind, search, maxChars })` | NDJSON records for locating and resolving objects |
|
||||
| Runtime handoff | `presentation.toProto()` | Serializable presentation data for host adapters |
|
||||
|
||||
## Minimal Patterns
|
||||
|
||||
Use these as the first API patterns to reach for:
|
||||
|
||||
```ts
|
||||
// Create, preview, inspect, then serialize.
|
||||
const presentation = Presentation.create({
|
||||
slideSize: { width: 1280, height: 720 },
|
||||
});
|
||||
const slide = presentation.slides.add();
|
||||
const preview = await presentation.export({ slide, format: "png", scale: 1 });
|
||||
const snapshot = await presentation.inspect({
|
||||
kind: "slide,textbox,shape,image,chart,table",
|
||||
maxChars: 4000,
|
||||
});
|
||||
const proto = presentation.toProto();
|
||||
```
|
||||
|
||||
```tsx
|
||||
// Compose structure with first-principles rows/columns.
|
||||
slide.compose(
|
||||
<row width="fill" height="fill" gap={28}>
|
||||
<column width={420} height="fill" gap={16}>
|
||||
<paragraph className="text-slate-950 text-5xl font-bold leading-tight">
|
||||
Title
|
||||
</paragraph>
|
||||
<paragraph className="text-slate-600 text-xl leading-relaxed">
|
||||
Editable copy in a fixed text column.
|
||||
</paragraph>
|
||||
</column>
|
||||
<box
|
||||
width="fill"
|
||||
height="fill"
|
||||
className="bg-slate-50 rounded-2xl shadow-sm"
|
||||
/>
|
||||
</row>,
|
||||
{ frame: { left: 56, top: 56, width: 1168, height: 608 }, baseUnit: 8 },
|
||||
);
|
||||
```
|
||||
|
||||
For 3-column and 12-column layouts, use [`references/cookbook/layout.md`](./references/cookbook/layout.md); keep spans local with `{ mode: "fr", value: 1 }` track objects.
|
||||
|
||||
Use `className` only for visual/text tokens such as `bg-*`, `rounded-*`,
|
||||
`shadow-*`, `text-*`, `font-*`, and `leading-*`. Use layout props for
|
||||
`width`, `height`, `gap`, `padding`, `align`, and `justify`.
|
||||
|
||||
## Reference Map
|
||||
|
||||
Open these references as needed:
|
||||
|
||||
- [`references/jsx.md`](./references/jsx.md) — compact JSX node surface and layout mechanics.
|
||||
- [`references/tokens.md`](./references/tokens.md) — Tailwind-like token reference for colors, text, radius, shadows, and `className`.
|
||||
- [`references/cookbook/layout.md`](./references/cookbook/layout.md) — first-principles layout recipes for rows, columns, 12-column grids, alignment, masks, and overlays.
|
||||
- [`references/cookbook/imported-deck.md`](./references/cookbook/imported-deck.md) — safe inspect, resolve, edit, preview, and re-inspect loops for existing decks.
|
||||
- [`references/presentation.spec.md`](./references/presentation.spec.md) — `Presentation` facade, slide collection, view controls, export/toProto, scripts.
|
||||
- [`references/slide.spec.md`](./references/slide.spec.md) — `Slide` API, backgrounds, placeholders, notes, export, auto-layout.
|
||||
- [`references/inspect.md`](./references/inspect.md) — grep-first snapshot (`inspect → rg → resolve/edit → re-inspect`) for loaded presentation data and templates.
|
||||
- [`references/help.md`](./references/help.md) — grep-first API and template lookup (`help → build/edit → inspect`) for presentation JS workflows.
|
||||
- [`references/layout.spec.md`](./references/layout.spec.md) — layouts, placeholders, and slide layout assignment.
|
||||
- [`references/master.spec.md`](./references/master.spec.md) — masters, layout linking, background refs, color maps.
|
||||
- [`references/theme.spec.md`](./references/theme.spec.md) — theme color schemes and hex maps.
|
||||
- [`references/styles.spec.md`](./references/styles.spec.md) — named text styles and flow through text.
|
||||
- [`references/rich-text.spec.md`](./references/rich-text.spec.md) — text blocks, ranges, links, list presets.
|
||||
- [`references/shapes.spec.md`](./references/shapes.spec.md) — shape geometry, custom Bézier curves, fills, strokes, rounded corners, shadows, and z-ordering.
|
||||
- [`references/connectors.md`](./references/connectors.md) — connected lines, arrows, side anchors, direct connection sites, and rerouting behavior.
|
||||
- [`references/fill.spec.md`](./references/fill.spec.md) — fill/stroke config shapes and color shorthands, solid, gradient, pattern.
|
||||
- [`references/images.spec.md`](./references/images.spec.md) — images, cropping, contain/cover framing, prompt placeholders.
|
||||
- [`references/tables.spec.md`](./references/tables.spec.md) — tables, merges, and cell text.
|
||||
- [`references/charts.spec.md`](./references/charts.spec.md) — charts, series, axes, legends, mini-chart YAML.
|
||||
- [`references/comments.md`](./references/comments.md) — comment authors, threads, replies, reactions, and resolving imported review threads.
|
||||
- [`references/auto-layout.spec.md`](./references/auto-layout.spec.md) — deterministic layout helpers for arranging shapes within frames.
|
||||
- [`references/speaker-notes.spec.md`](./references/speaker-notes.spec.md) — speaker notes surface and visibility toggles.
|
||||
Generated
Vendored
+100
@@ -0,0 +1,100 @@
|
||||
# Auto Layout
|
||||
|
||||
`slide.autoLayout(...)` places shapes within a frame using deterministic spacing.
|
||||
Use `slide.compose(<row>/<column>/<grid>)` for new structured JSX layouts. Use
|
||||
`slide.autoLayout(...)` when repositioning existing facade shapes, especially
|
||||
imported or generated shapes.
|
||||
|
||||
## Pattern
|
||||
|
||||
```ts
|
||||
slide.autoLayout(shapes, {
|
||||
direction,
|
||||
frame,
|
||||
align,
|
||||
horizontalGap,
|
||||
verticalGap,
|
||||
horizontalPadding,
|
||||
verticalPadding,
|
||||
});
|
||||
```
|
||||
|
||||
## Inputs
|
||||
|
||||
- `direction`: horizontal or vertical flow.
|
||||
- `frame`: `"slide"`, container `Shape`, or explicit `{ left, top, width, height }`.
|
||||
- `align`: 3x3 group alignment within the frame.
|
||||
- Gap and padding values use pixels.
|
||||
|
||||
## Inline Types
|
||||
|
||||
```ts
|
||||
type AutoLayoutOptions = {
|
||||
direction?: "horizontal" | "vertical";
|
||||
frame?:
|
||||
| "slide"
|
||||
| Shape
|
||||
| { left: number; top: number; width: number; height: number };
|
||||
align?:
|
||||
| "center"
|
||||
| "topLeft"
|
||||
| "topCenter"
|
||||
| "topRight"
|
||||
| "left"
|
||||
| "right"
|
||||
| "bottomLeft"
|
||||
| "bottomCenter"
|
||||
| "bottomRight";
|
||||
horizontalGap?: number | "auto";
|
||||
verticalGap?: number | "auto";
|
||||
horizontalPadding?: number;
|
||||
verticalPadding?: number;
|
||||
};
|
||||
```
|
||||
|
||||
## Shape Prep
|
||||
|
||||
```ts
|
||||
for (const shape of shapes) {
|
||||
shape.position = {
|
||||
width: shapeWidthPx,
|
||||
height: shapeHeightPx,
|
||||
};
|
||||
}
|
||||
|
||||
slide.autoLayout(shapes, layoutConfig);
|
||||
```
|
||||
|
||||
## Cookbook
|
||||
|
||||
```ts
|
||||
// Equal KPI row.
|
||||
const kpiShapes = metrics.map((metric) =>
|
||||
slide.shapes.add({
|
||||
geometry: "roundRect",
|
||||
position: { width: 240, height: 132 },
|
||||
fill: "white",
|
||||
line: { style: "solid", fill: "slate-200", width: 1 },
|
||||
borderRadius: "rounded-xl",
|
||||
}),
|
||||
);
|
||||
|
||||
slide.autoLayout(kpiShapes, {
|
||||
direction: "horizontal",
|
||||
frame: { left: 80, top: 160, width: 1120, height: 160 },
|
||||
horizontalGap: "auto",
|
||||
align: "center",
|
||||
});
|
||||
```
|
||||
|
||||
```ts
|
||||
// Vertical callout stack inside an existing shape frame.
|
||||
slide.autoLayout(callouts, {
|
||||
direction: "vertical",
|
||||
frame: frameShape,
|
||||
verticalGap: 14,
|
||||
horizontalPadding: 24,
|
||||
verticalPadding: 24,
|
||||
align: "topLeft",
|
||||
});
|
||||
```
|
||||
Generated
Vendored
+330
@@ -0,0 +1,330 @@
|
||||
# Charts
|
||||
|
||||
`slide.charts` creates chart elements with slide placement and chart configuration.
|
||||
|
||||
## Resolved From Inspect
|
||||
|
||||
```ts
|
||||
const chart = presentation.resolve("ch/b2c3d4e5");
|
||||
chart.title = "Updated chart title";
|
||||
chart.yAxis = { numberFormatCode: "$#,##0M" };
|
||||
chart.series.getItemAt(0).values = [3.1, 3.7, 4.2, 4.8];
|
||||
```
|
||||
|
||||
Use `presentation.inspect({ kind: "chart", search })` to find the `ch/...`
|
||||
anchor id. If an imported chart resolves as an image, preserve it as an image or
|
||||
rebuild it as a native chart intentionally.
|
||||
|
||||
## Add Chart
|
||||
|
||||
```ts
|
||||
const chart = slide.charts.add(chartType, {
|
||||
position,
|
||||
title,
|
||||
titleTextStyle,
|
||||
categories,
|
||||
series,
|
||||
hasLegend,
|
||||
legend,
|
||||
barOptions,
|
||||
lineOptions,
|
||||
areaOptions,
|
||||
pieOptions,
|
||||
doughnutOptions,
|
||||
treemapOptions,
|
||||
mapOptions,
|
||||
funnelOptions,
|
||||
boxWhiskerOptions,
|
||||
histogramOptions,
|
||||
view3d,
|
||||
scatterOptions,
|
||||
radarOptions,
|
||||
bubbleOptions,
|
||||
xAxis,
|
||||
yAxis,
|
||||
dataLabels,
|
||||
dataTable,
|
||||
chartFill,
|
||||
chartLine,
|
||||
plotAreaFill,
|
||||
plotAreaLine,
|
||||
});
|
||||
```
|
||||
|
||||
Small chart option enums are listed below.
|
||||
|
||||
## Chart Inline Types
|
||||
|
||||
```ts
|
||||
type ChartTypeName =
|
||||
| "line" | "pie" | "bar" | "doughnut" | "scatter" | "bubble" | "radar"
|
||||
| "treemap" | "sunburst" | "map" | "waterfall" | "line3D" | "pie3D"
|
||||
| "area3D" | "bar3D" | "funnel" | "histogram" | "boxWhisker" | "stock"
|
||||
| "surface3D" | "ofPie" | "surface" | "pareto" | "combo" | "area";
|
||||
|
||||
type ChartConfig = {
|
||||
position?: { left?: number; top?: number; width?: number; height?: number };
|
||||
title?: string;
|
||||
roundedCorners?: boolean | null;
|
||||
titlePlacement?: "none" | "aboveChart" | "centeredOverlay";
|
||||
titleTextStyle?: ChartTextStyleConfig;
|
||||
categories?: string[];
|
||||
series?: ChartSeriesConfig[];
|
||||
hasLegend?: boolean;
|
||||
legend?: ChartLegendConfig;
|
||||
barOptions?: { direction?: "bar" | "column"; grouping?: "clustered" | "stacked" | "percentStacked"; varyColors?: boolean; gapWidth?: number; gapDepth?: number; overlap?: number; bar3dShape?: number };
|
||||
lineOptions?: { grouping?: "standard" | "stacked" | "percentStacked"; smooth?: boolean; varyColors?: boolean };
|
||||
areaOptions?: { grouping?: "standard" | "stacked" | "percentStacked"; varyColors?: boolean };
|
||||
pieOptions?: { firstSliceAngle?: number };
|
||||
doughnutOptions?: { holeSize?: number; firstSliceAngle?: number };
|
||||
treemapOptions?: { parentLabelLayout?: "none" | "overlapping" | "banner" };
|
||||
mapOptions?: { mapArea?: "world" | "auto" | "dataOnly" | "region"; projection?: "mercator" | "auto" | "miller" | "albers"; labelLayout?: "none" | "bestFit" | "showAll"; dataLevel?: "auto" | "county" | "postalCode" | "countryOrRegion" | "stateOrProvince" | "stateCode" | "countyCode" | "countryOrRegionCode"; showUnknown?: boolean; onlyRegionsWithData?: boolean };
|
||||
funnelOptions?: { gapWidth?: number };
|
||||
boxWhiskerOptions?: { showMeanLine?: boolean; showMeanMarker?: boolean; showNonOutliers?: boolean; showOutliers?: boolean; quartileMethod?: "inclusive" | "exclusive" };
|
||||
histogramOptions?: { binWidth?: number | null; binCount?: number | null; underflow?: number | null; overflow?: number | null; intervalClosed?: number; aggregated?: boolean };
|
||||
view3d?: { rotX?: number; rotY?: number; perspective?: number; rightAngleAxes?: boolean };
|
||||
scatterOptions?: { style?: "line" | "lineWithMarkers" | "marker" | "smooth" | "smoothWithMarkers"; varyColors?: boolean };
|
||||
radarOptions?: { style?: "standard" | "marker" | "filled"; varyColors?: boolean };
|
||||
bubbleOptions?: { scale?: number | null; sizeRepresents?: "area" | "width" | null; showNegative?: boolean | null };
|
||||
xAxis?: ChartAxisConfig;
|
||||
yAxis?: ChartAxisConfig;
|
||||
dataLabels?: ChartDataLabelsConfig;
|
||||
dataTable?: ChartDataTableConfig;
|
||||
chartFill?: FillConfig;
|
||||
chartLine?: LineConfig;
|
||||
plotAreaFill?: FillConfig;
|
||||
plotAreaLine?: LineConfig;
|
||||
displayBlanksAs?: "zero" | "gap" | "span" | null;
|
||||
styleIndex?: number;
|
||||
};
|
||||
```
|
||||
|
||||
## Chart Family Options
|
||||
|
||||
```ts
|
||||
histogram.histogramOptions = { binWidth: 5 };
|
||||
histogram.histogramOptions = { binCount: 8, underflow: 0, overflow: 30 };
|
||||
histogram.histogramOptions = { binWidth: null, binCount: null };
|
||||
histogram.histogramOptions = { underflow: null, overflow: null };
|
||||
bubble.bubbleOptions = { scale: 150, sizeRepresents: "area" };
|
||||
bubble.bubbleOptions = { scale: null, sizeRepresents: null };
|
||||
bubble.bubbleOptions = { showNegative: true };
|
||||
```
|
||||
|
||||
## Grouped Edits
|
||||
|
||||
```ts
|
||||
chart.xAxis = axisConfig;
|
||||
chart.yAxis = axisConfig;
|
||||
chart.legend = legendConfig;
|
||||
chart.dataLabels = dataLabelsConfig;
|
||||
chart.dataTable = dataTableConfig;
|
||||
```
|
||||
|
||||
### Data Labels
|
||||
|
||||
```ts
|
||||
chart.dataLabels = { showValue: true, position: "outEnd" };
|
||||
chart.dataLabels = { textStyle: { fontSize: 14 } };
|
||||
chart.dataLabels.showCategoryName = true;
|
||||
|
||||
const series = chart.series.getItemAt(seriesIndex);
|
||||
series.dataLabels = { showValue: false, showSeriesName: true };
|
||||
series.dataLabels.showSeriesName = false;
|
||||
```
|
||||
|
||||
Config assignments update supplied fields and preserve omitted values. New label
|
||||
collections initialize all seven `show*` flags to `false`. A series without its
|
||||
own label collection inherits chart labels; omitted point flags inherit series
|
||||
or chart labels.
|
||||
|
||||
### Axis Placement
|
||||
|
||||
```ts
|
||||
chart.xAxis = { crossesAt: 2 }; // The value axis crosses at category 2.
|
||||
chart.yAxis = { crossesAt: 25 }; // The category axis crosses at value 25.
|
||||
chart.yAxis = { tickLabelPosition: "high" };
|
||||
```
|
||||
|
||||
## Series
|
||||
|
||||
```ts
|
||||
const chart = slide.charts.add(chartType, {
|
||||
categories,
|
||||
series: [
|
||||
{
|
||||
name: seriesName,
|
||||
categories,
|
||||
values,
|
||||
xValues,
|
||||
categoryPaths,
|
||||
fill: fillConfig,
|
||||
line: lineConfig,
|
||||
marker: markerConfig,
|
||||
points,
|
||||
dataLabels: dataLabelsConfig,
|
||||
dataLabelOverrides,
|
||||
trendlines,
|
||||
errorBars,
|
||||
},
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
## Series Inline Type
|
||||
|
||||
```ts
|
||||
type ChartSeriesConfig = {
|
||||
name: string;
|
||||
categories?: string[];
|
||||
values?: Array<number | null>;
|
||||
xValues?: Array<number | null>;
|
||||
categoryPaths?: string[][];
|
||||
bubbleSizes?: Array<number | null>;
|
||||
bubbleSizeFormula?: string;
|
||||
bubbleSizesFormatCode?: string;
|
||||
explosion?: number;
|
||||
smooth?: boolean;
|
||||
fill?: FillConfig;
|
||||
line?: LineConfig;
|
||||
stroke?: LineConfig;
|
||||
// Scatter outline color defaults to the marker's solid fill; explicit stroke fills take precedence.
|
||||
marker?: { symbol?: "circle" | "diamond" | "dot" | "none" | "plus" | "square" | "star" | "triangle" | "x"; size?: number; fill?: FillConfig };
|
||||
points?: Array<{ idx: number; fill?: FillConfig; line?: LineConfig; stroke?: LineConfig }>;
|
||||
dataLabels?: ChartDataLabelsConfig;
|
||||
dataLabelOverrides?: Array<{ idx: number; text?: string; separator?: string; position?: string; fill?: FillConfig; line?: LineConfig; stroke?: LineConfig; showValue?: boolean; showSeriesName?: boolean; showCategoryName?: boolean; showPercent?: boolean; textStyle?: ChartTextStyleConfig }>;
|
||||
trendlines?: Array<{
|
||||
type?: "linear" | "exponential" | "logarithmic" | "polynomial" | "power" | "movingAverage";
|
||||
name?: string;
|
||||
polynomialOrder?: number;
|
||||
movingAveragePeriod?: number;
|
||||
forecastForward?: number;
|
||||
forecastBackward?: number;
|
||||
intercept?: number;
|
||||
displayEquation?: boolean;
|
||||
displayRSquared?: boolean;
|
||||
line?: LineConfig;
|
||||
label?: { text?: string; textStyle?: ChartTextStyleConfig; fill?: FillConfig; line?: LineConfig };
|
||||
}>;
|
||||
errorBars?: { type?: "standardError" | "percentage" | "standardDeviation" | "none"; value?: number; endStyle?: "cap" | "noCap"; line?: LineConfig };
|
||||
valuesFormatCode?: string;
|
||||
xValuesFormatCode?: string;
|
||||
};
|
||||
```
|
||||
|
||||
## Data Label Overrides
|
||||
|
||||
```ts
|
||||
const override = chart.series
|
||||
.getItemAt(seriesIndex)
|
||||
.dataLabelOverrides.add(dataPointIdx);
|
||||
override.text = labelText;
|
||||
override.position = labelPosition;
|
||||
override.textStyle.fontSize = fontSizePx;
|
||||
override.textStyle.fill = textFill;
|
||||
override.fill = fillConfig;
|
||||
override.stroke = lineConfig;
|
||||
```
|
||||
|
||||
## Chart Areas
|
||||
|
||||
```ts
|
||||
const chart = slide.charts.add(chartType, {
|
||||
chartFill,
|
||||
plotAreaFill,
|
||||
});
|
||||
```
|
||||
|
||||
## Axis, Legend, Label Inline Types
|
||||
|
||||
```ts
|
||||
type ChartTextStyleConfig = {
|
||||
fontSize?: number;
|
||||
fill?: FillConfig;
|
||||
bold?: boolean;
|
||||
italic?: boolean;
|
||||
underline?: string;
|
||||
alignment?: "left" | "center" | "right" | "justify";
|
||||
};
|
||||
|
||||
type ChartLegendConfig = {
|
||||
position?: "left" | "top" | "topRight" | "right" | "bottom";
|
||||
overlay?: boolean;
|
||||
fill?: FillConfig;
|
||||
line?: LineConfig;
|
||||
textStyle?: ChartTextStyleConfig;
|
||||
};
|
||||
|
||||
type ChartDataLabelsConfig = {
|
||||
visible?: boolean;
|
||||
deleted?: boolean;
|
||||
position?: "center" | "inEnd" | "outEnd" | "left" | "right" | "top" | "bottom" | "insideBase" | "bestFit" | "dataCallout";
|
||||
showValue?: boolean;
|
||||
showSeriesName?: boolean;
|
||||
showCategoryName?: boolean;
|
||||
showLegendKey?: boolean;
|
||||
showPercent?: boolean;
|
||||
showBubbleSize?: boolean;
|
||||
showLeaderLines?: boolean;
|
||||
numberFormatCode?: string;
|
||||
numberFormatSourceLinked?: boolean;
|
||||
separator?: string;
|
||||
textStyle?: ChartTextStyleConfig;
|
||||
fill?: FillConfig;
|
||||
line?: LineConfig;
|
||||
};
|
||||
|
||||
type ChartAxisConfig = {
|
||||
visible?: boolean;
|
||||
title?: string | { text?: string; textStyle?: ChartTextStyleConfig };
|
||||
numberFormatCode?: string;
|
||||
min?: number;
|
||||
max?: number;
|
||||
majorUnit?: number;
|
||||
minorUnit?: number;
|
||||
position?: "bottom" | "left" | "right" | "top";
|
||||
tickLabelPosition?: "nextTo" | "high" | "low" | "none" | string;
|
||||
labelOffsetPercent?: number; // Category-axis font-size percentage; 0–1000, default 100.
|
||||
textStyle?: ChartTextStyleConfig;
|
||||
line?: LineConfig;
|
||||
majorGridlines?: LineConfig | null;
|
||||
minorGridlines?: LineConfig | null;
|
||||
};
|
||||
```
|
||||
|
||||
## Cookbook
|
||||
|
||||
```ts
|
||||
// Executive horizontal bar chart.
|
||||
slide.charts.add("bar", {
|
||||
position: { left: 96, top: 160, width: 720, height: 360 },
|
||||
categories: ["Enterprise", "Mid-market", "SMB"],
|
||||
series: [{ name: "ARR", values: [42, 28, 17], fill: "#2563eb" }],
|
||||
barOptions: { direction: "bar", grouping: "clustered", gapWidth: 44 },
|
||||
hasLegend: false,
|
||||
xAxis: { visible: false, majorGridlines: null },
|
||||
yAxis: { textStyle: { fill: "#475569", fontSize: 13 }, line: { style: "solid", fill: "#e2e8f0", width: 1 } },
|
||||
dataLabels: { showValue: true, position: "outEnd", textStyle: { fill: "#0f172a", fontSize: 13, bold: true } },
|
||||
});
|
||||
```
|
||||
|
||||
```ts
|
||||
// Compact trend line with muted grid.
|
||||
slide.charts.add("line", {
|
||||
position: { left: 96, top: 150, width: 880, height: 280 },
|
||||
categories: ["Jan", "Feb", "Mar", "Apr"],
|
||||
series: [{ name: "Conversion", values: [31, 34, 37, 43], line: { style: "solid", fill: "#0f766e", width: 3 } }],
|
||||
legend: { position: "bottom", overlay: false },
|
||||
yAxis: { numberFormatCode: "0%", majorGridlines: { style: "solid", fill: "#e2e8f0", width: 1 } },
|
||||
});
|
||||
```
|
||||
|
||||
```ts
|
||||
// Doughnut chart with labels outside.
|
||||
slide.charts.add("doughnut", {
|
||||
categories: ["Product", "Sales", "Support"],
|
||||
series: [{ name: "Share", values: [52, 31, 17] }],
|
||||
dataLabels: { showPercent: true, showCategoryName: true, position: "outEnd" },
|
||||
legend: { position: "right" },
|
||||
});
|
||||
```
|
||||
Generated
Vendored
+103
@@ -0,0 +1,103 @@
|
||||
# Comments
|
||||
|
||||
Presentation comments use people, threads, replies, reactions, and thread state.
|
||||
|
||||
## Current Author
|
||||
|
||||
```ts
|
||||
presentation.comments.setSelf({
|
||||
displayName,
|
||||
initials,
|
||||
email,
|
||||
});
|
||||
```
|
||||
|
||||
## Person Inline Type
|
||||
|
||||
```ts
|
||||
type PersonConfig = {
|
||||
id?: string;
|
||||
displayName: string;
|
||||
initials?: string;
|
||||
email?: string;
|
||||
avatarUrl?: string;
|
||||
userId?: string;
|
||||
providerId?: string;
|
||||
};
|
||||
```
|
||||
|
||||
## Element Thread
|
||||
|
||||
```ts
|
||||
const thread = presentation.comments.addThread({ element }, bodyText, {
|
||||
position,
|
||||
});
|
||||
|
||||
const reply = thread.addReply(replyText);
|
||||
reply.toggleReaction(reactionText);
|
||||
thread.resolve();
|
||||
thread.reopen();
|
||||
```
|
||||
|
||||
## Thread Inline Types
|
||||
|
||||
```ts
|
||||
type CommentTarget =
|
||||
| { slide: Slide }
|
||||
| { element: Shape | ImageElement | Table | ChartElement }
|
||||
| { textRange: TextRange }
|
||||
| { textMatch: { element: Shape; query: string; occurrence?: number } };
|
||||
|
||||
type ThreadAddOptions = {
|
||||
author?: Person | PersonConfig | { id: string };
|
||||
createdAt?: string;
|
||||
position?: { x: number; y: number; unit?: "px" | "emu" };
|
||||
};
|
||||
```
|
||||
|
||||
## Slide And Text Threads
|
||||
|
||||
```ts
|
||||
presentation.comments.addThread({ slide }, bodyText, { position });
|
||||
|
||||
presentation.comments.addThread(
|
||||
{ textMatch: { element, query, occurrence } },
|
||||
bodyText,
|
||||
);
|
||||
```
|
||||
|
||||
## Cookbook
|
||||
|
||||
```ts
|
||||
// Add a review comment to exact text.
|
||||
presentation.comments.setSelf({
|
||||
displayName: "Presentation Reviewer",
|
||||
initials: "PR",
|
||||
email: "reviewer@example.com",
|
||||
});
|
||||
|
||||
const thread = presentation.comments.addThread(
|
||||
{ textMatch: { element: titleShape, query: "Q4", occurrence: 0 } },
|
||||
"Check whether this should be FY2026 Q1.",
|
||||
);
|
||||
thread.addReply("Leaving this unresolved for owner review.");
|
||||
```
|
||||
|
||||
```ts
|
||||
// Resolve an imported thread after an edit.
|
||||
const self = presentation.comments.setSelf({
|
||||
displayName: "Presentation Editor",
|
||||
initials: "PE",
|
||||
email: "editor@example.com",
|
||||
});
|
||||
|
||||
const thread = presentation.resolve(threadAnchorId);
|
||||
thread.addReply("Updated the chart title and source note.", { author: self });
|
||||
thread.resolve(self);
|
||||
|
||||
const verified = await presentation.inspect({
|
||||
kind: "thread",
|
||||
target: { id: threadAnchorId, beforeLines: 0, afterLines: 2 },
|
||||
maxChars: 2000,
|
||||
});
|
||||
```
|
||||
Generated
Vendored
+225
@@ -0,0 +1,225 @@
|
||||
# Connectors
|
||||
|
||||
`slide.shapes.connect` creates connector lines that stay attached to slide
|
||||
shapes. Use it for arrows, flow links, callouts, dependency lines, and other
|
||||
relationships between positioned shapes.
|
||||
|
||||
Use direct `geometry: "connector"` creation only when you need exact connection
|
||||
site indexes.
|
||||
|
||||
## Connect Shapes
|
||||
|
||||
```ts
|
||||
const connector = slide.shapes.connect(sourceShape, targetShape, {
|
||||
kind: "elbow",
|
||||
fromSide: "right",
|
||||
toSide: "left",
|
||||
line: { style: "solid", fill: "slate-500", width: 2 },
|
||||
head: { type: "arrow", width: "med", length: "med" },
|
||||
});
|
||||
```
|
||||
|
||||
Endpoints accept shape facades or shape ids. `fromSide` and `toSide` accept
|
||||
`"top"`, `"left"`, `"bottom"`, or `"right"` and resolve to the nearest
|
||||
connection site for that shape geometry. When you omit side and index options,
|
||||
the API chooses a connection pair from the relative shape positions.
|
||||
|
||||
`kind` defaults to `"elbow"` for `slide.shapes.connect(...)`.
|
||||
|
||||
## Connect Inline Types
|
||||
|
||||
```ts
|
||||
type ConnectorSide = "top" | "left" | "bottom" | "right";
|
||||
|
||||
type ShapeConnectOptions = {
|
||||
kind?:
|
||||
| "straight"
|
||||
| "elbow"
|
||||
| "elbow2"
|
||||
| "elbow3"
|
||||
| "elbow4"
|
||||
| "elbow5"
|
||||
| "curved";
|
||||
fromSide?: ConnectorSide;
|
||||
toSide?: ConnectorSide;
|
||||
fromIdx?: number;
|
||||
toIdx?: number;
|
||||
line?: LineConfig;
|
||||
head?: LineEndConfig;
|
||||
tail?: LineEndConfig;
|
||||
cap?: "flat" | "round" | "square";
|
||||
join?: "round" | "bevel" | "miter";
|
||||
};
|
||||
|
||||
type LineEndConfig = {
|
||||
type?: "none" | "triangle" | "stealth" | "diamond" | "oval" | "arrow";
|
||||
width?: "sm" | "med" | "lg";
|
||||
length?: "sm" | "med" | "lg";
|
||||
};
|
||||
```
|
||||
|
||||
## Anchor Choice
|
||||
|
||||
Use side anchors for readable authoring:
|
||||
|
||||
```ts
|
||||
slide.shapes.connect(sourceShape, targetShape, {
|
||||
fromSide: "bottom",
|
||||
toSide: "top",
|
||||
kind: "elbow",
|
||||
line: { style: "dashed", fill: "accent1", width: 2 },
|
||||
});
|
||||
```
|
||||
|
||||
Use explicit connection site indexes when you need an exact preset-geometry site:
|
||||
|
||||
```ts
|
||||
const fromIdx = slide.shapes.getConnectionSiteIndex(sourceShape, "right");
|
||||
const toIdx = slide.shapes.getConnectionSiteIndex(targetShape, "left");
|
||||
|
||||
slide.shapes.connect(sourceShape.id, targetShape.id, {
|
||||
fromIdx,
|
||||
toIdx,
|
||||
kind: "straight",
|
||||
line: { style: "solid", fill: "slate-700", width: 2 },
|
||||
});
|
||||
```
|
||||
|
||||
Connection site indexes are PowerPoint preset geometry connection points. Side
|
||||
anchors map to the closest useful preset site for rectangles, ellipses, and
|
||||
other shapes.
|
||||
|
||||
## Direct Connector Shape
|
||||
|
||||
```ts
|
||||
const connector = slide.shapes.add({
|
||||
geometry: "connector",
|
||||
kind: "curved",
|
||||
from: sourceShape,
|
||||
fromIdx: 3,
|
||||
to: targetShape,
|
||||
toIdx: 1,
|
||||
line: { style: "solid", fill: "accent1", width: 2 },
|
||||
tail: { type: "triangle", width: "med", length: "med" },
|
||||
});
|
||||
```
|
||||
|
||||
## Unattached Connector
|
||||
|
||||
```ts
|
||||
const arrow = slide.shapes.add({
|
||||
geometry: "connector",
|
||||
kind: "straight",
|
||||
position: { left: 40, top: 160, width: 240, height: 0 },
|
||||
line: { fill: "accent1", width: 2 },
|
||||
tail: { type: "arrow" },
|
||||
});
|
||||
```
|
||||
|
||||
## One Attached Endpoint
|
||||
|
||||
```ts
|
||||
const connector = slide.shapes.add({
|
||||
geometry: "connector",
|
||||
kind: "straight",
|
||||
from: sourceShape,
|
||||
fromIdx: slide.shapes.getConnectionSiteIndex(sourceShape, "right"),
|
||||
position: { left: 40, top: 160, width: 240, height: 0 },
|
||||
line: { fill: "accent1", width: 2 },
|
||||
tail: { type: "arrow" },
|
||||
});
|
||||
```
|
||||
|
||||
## Direct Connector Inline Type
|
||||
|
||||
```ts
|
||||
type ConnectorConfig = {
|
||||
geometry: "connector";
|
||||
from?: Shape | string;
|
||||
fromIdx?: number;
|
||||
to?: Shape | string;
|
||||
toIdx?: number;
|
||||
position?: PositionConfig;
|
||||
kind?:
|
||||
| "straight"
|
||||
| "elbow"
|
||||
| "elbow2"
|
||||
| "elbow3"
|
||||
| "elbow4"
|
||||
| "elbow5"
|
||||
| "curved";
|
||||
line?: LineConfig;
|
||||
head?: LineEndConfig;
|
||||
tail?: LineEndConfig;
|
||||
cap?: "flat" | "round" | "square";
|
||||
join?: "round" | "bevel" | "miter";
|
||||
};
|
||||
```
|
||||
|
||||
Connectors support line styling and line ends, but not `borderRadius` or
|
||||
`shadow`.
|
||||
|
||||
## Edit Existing Connectors
|
||||
|
||||
```ts
|
||||
const connector = presentation.resolve(connectorAnchorId);
|
||||
const nextFromIdx = slide.shapes.getConnectionSiteIndex(
|
||||
nextSourceShape,
|
||||
"right",
|
||||
);
|
||||
const nextToIdx = slide.shapes.getConnectionSiteIndex(nextTargetShape, "left");
|
||||
|
||||
connector.setConnectorFrom(nextSourceShape, nextFromIdx);
|
||||
connector.setConnectorTo(nextTargetShape.id, nextToIdx);
|
||||
connector.line = { style: "solid", fill: "slate-800", width: 2 };
|
||||
connector.bringToFront();
|
||||
```
|
||||
|
||||
Use `presentation.inspect({ kind: "shape", search })` to find connector anchor
|
||||
ids. Connector facades expose `connector`, `connectorLineStyle`,
|
||||
`connectorHead`, and `connectorTail` for readback.
|
||||
|
||||
## Routing And Ordering
|
||||
|
||||
New connectors are sent behind shapes by default so boxes and labels remain
|
||||
readable. Call `connector.bringToFront()` when the connector should sit above
|
||||
other elements.
|
||||
|
||||
## Cookbook
|
||||
|
||||
```ts
|
||||
// Arrow from one card to another.
|
||||
slide.shapes.connect(sourceCard, targetCard, {
|
||||
kind: "elbow",
|
||||
fromSide: "right",
|
||||
toSide: "left",
|
||||
line: { style: "solid", fill: "slate-500", width: 2 },
|
||||
head: { type: "arrow", width: "med", length: "med" },
|
||||
});
|
||||
```
|
||||
|
||||
```ts
|
||||
// Bidirectional relationship line.
|
||||
slide.shapes.connect(leftShape, rightShape, {
|
||||
kind: "straight",
|
||||
fromSide: "right",
|
||||
toSide: "left",
|
||||
line: { style: "dashed", fill: "accent2", width: 2 },
|
||||
head: { type: "arrow", width: "sm", length: "sm" },
|
||||
tail: { type: "arrow", width: "sm", length: "sm" },
|
||||
});
|
||||
```
|
||||
|
||||
```ts
|
||||
// Curved connector with explicit preset connection sites.
|
||||
slide.shapes.add({
|
||||
geometry: "connector",
|
||||
kind: "curved",
|
||||
from: sourceShape,
|
||||
fromIdx: slide.shapes.getConnectionSiteIndex(sourceShape, "bottom"),
|
||||
to: targetShape,
|
||||
toIdx: slide.shapes.getConnectionSiteIndex(targetShape, "top"),
|
||||
line: { style: "solid", fill: "accent1", width: 2 },
|
||||
tail: { type: "triangle", width: "med", length: "med" },
|
||||
});
|
||||
```
|
||||
Generated
Vendored
+187
@@ -0,0 +1,187 @@
|
||||
# Imported Deck Cookbook
|
||||
|
||||
Use these recipes when editing an existing presentation. The goal is targeted,
|
||||
type-aware edits with a preview and a small verification snapshot.
|
||||
|
||||
For imported decks, render the affected slide before and after focused edits,
|
||||
export layout JSON before and after when object placement matters, and use a
|
||||
deck montage before/after when a change may affect multiple slides.
|
||||
|
||||
## Load A PPTX
|
||||
|
||||
```ts
|
||||
const presentation = await Presentation.load("input.pptx");
|
||||
```
|
||||
|
||||
## Edit Loop
|
||||
|
||||
```ts
|
||||
const before = await presentation.inspect({
|
||||
kind: "slide,textbox,shape,image,table,chart,notes,thread,layout",
|
||||
search: "Revenue",
|
||||
maxChars: 8000,
|
||||
});
|
||||
|
||||
// Pick an exact anchor id from `before`; use inspect ids instead of slide indexes.
|
||||
const target = presentation.resolve(anchorId);
|
||||
|
||||
// slideAnchorId is the `sl/...` id from inspect for the affected slide.
|
||||
const slide = presentation.resolve(slideAnchorId);
|
||||
const previewBefore = await slide.export({ format: "png", scale: 2 });
|
||||
const layoutBefore = await slide.export({ format: "layout" });
|
||||
const montageBefore = await presentation.export({
|
||||
format: "webp",
|
||||
montage: true,
|
||||
scale: 1,
|
||||
});
|
||||
|
||||
target.text.replace("Revenue", "Revenue outlook");
|
||||
|
||||
const previewAfter = await slide.export({ format: "png", scale: 2 });
|
||||
const layoutAfter = await slide.export({ format: "layout" });
|
||||
const montageAfter = await presentation.export({
|
||||
format: "webp",
|
||||
montage: true,
|
||||
scale: 1,
|
||||
});
|
||||
|
||||
const after = await presentation.inspect({
|
||||
target: { id: anchorId, beforeLines: 2, afterLines: 2 },
|
||||
kind: "textbox,shape",
|
||||
maxChars: 2000,
|
||||
});
|
||||
```
|
||||
|
||||
## Placeholder Edit
|
||||
|
||||
```ts
|
||||
const layoutSnapshot = await presentation.inspect({
|
||||
kind: "slide,layout,textbox,shape",
|
||||
search: "Click to add title",
|
||||
maxChars: 6000,
|
||||
});
|
||||
|
||||
// slideAnchorId is the `sl/...` id from inspect for this slide.
|
||||
const slide = presentation.resolve(slideAnchorId);
|
||||
const title = slide.placeholders.getItem("title");
|
||||
title.text = "Updated executive summary";
|
||||
```
|
||||
|
||||
Edit a slide placeholder for a local content change. Edit a layout or master
|
||||
only when the intended change is global.
|
||||
Inspect records use 1-based `slide` numbers for display; `slides.getItem(index)`
|
||||
is 0-based. Prefer resolving the `sl/...` anchor from inspect.
|
||||
|
||||
## Master/Layout Blast Radius
|
||||
|
||||
```ts
|
||||
// layoutId comes from inspect/layout export metadata; use it for search and comparison.
|
||||
const affected = await presentation.inspect({
|
||||
kind: "slide,layout",
|
||||
search: layoutId,
|
||||
maxChars: 6000,
|
||||
});
|
||||
```
|
||||
|
||||
Inspect affected layouts and slides before changing a master, layout, theme
|
||||
color, or placeholder geometry. Use layout ids for comparison/search, then
|
||||
resolve affected slides through their `sl/...` ids before editing. These edits
|
||||
can update many slides.
|
||||
|
||||
## Preserve Imported Image Placement
|
||||
|
||||
```ts
|
||||
const image = presentation.resolve(imageAnchorId);
|
||||
const oldFrame = image.frame;
|
||||
const oldCrop = image.crop;
|
||||
const oldFit = image.fit;
|
||||
const oldAlt = image.alt;
|
||||
const oldPrompt = image.prompt;
|
||||
const oldGeometry = image.geometry;
|
||||
const oldBorderRadius = image.borderRadius;
|
||||
const oldRotation = image.rotation;
|
||||
const oldFlipHorizontal = image.flipHorizontal;
|
||||
const oldFlipVertical = image.flipVertical;
|
||||
const oldLockAspectRatio = image.lockAspectRatio;
|
||||
|
||||
image.replace({
|
||||
blob: replacementBytes,
|
||||
contentType: "image/png",
|
||||
alt: oldAlt ?? "Updated product screenshot",
|
||||
...(oldFit ? { fit: oldFit } : {}),
|
||||
...(oldPrompt ? { prompt: oldPrompt } : {}),
|
||||
});
|
||||
image.frame = oldFrame;
|
||||
image.crop = oldCrop;
|
||||
image.geometry = oldGeometry;
|
||||
image.borderRadius = oldBorderRadius;
|
||||
image.rotation = oldRotation;
|
||||
image.flipHorizontal = oldFlipHorizontal;
|
||||
image.flipVertical = oldFlipVertical;
|
||||
image.lockAspectRatio = oldLockAspectRatio;
|
||||
```
|
||||
|
||||
Render the slide after replacement and verify subject crop, aspect ratio,
|
||||
rounded mask, and legibility. Preserve placement-affecting properties unless the
|
||||
edit explicitly changes them. Concrete source replacements produce concrete
|
||||
images; pass `prompt` when it should remain available as regeneration metadata.
|
||||
|
||||
## Existing Table And Chart Edits
|
||||
|
||||
```ts
|
||||
const table = presentation.resolve(tableAnchorId);
|
||||
table.cells.set(1, 2, "$4.2M");
|
||||
table.getCell(1, 2).text.style = "Body Small";
|
||||
|
||||
const chart = presentation.resolve(chartAnchorId);
|
||||
chart.xAxis = { title: "Quarter" };
|
||||
chart.yAxis = { numberFormatCode: "$#,##0M" };
|
||||
chart.series.getItemAt(0).values = [3.1, 3.7, 4.2, 4.8];
|
||||
|
||||
await presentation.inspect({
|
||||
kind: "table,chart",
|
||||
target: { id: chartAnchorId, beforeLines: 3, afterLines: 3 },
|
||||
maxChars: 3000,
|
||||
});
|
||||
```
|
||||
|
||||
If an imported chart or table resolves as an image, preserve it as an image or
|
||||
rebuild it as a native chart/table intentionally.
|
||||
|
||||
## Comments And Speaker Notes
|
||||
|
||||
```ts
|
||||
const review = await presentation.inspect({
|
||||
kind: "thread,notes,slide,textbox",
|
||||
search: "TODO",
|
||||
maxChars: 8000,
|
||||
});
|
||||
|
||||
const self = presentation.comments.setSelf({
|
||||
displayName: "Presentation Editor",
|
||||
initials: "PE",
|
||||
email: "presentation@example.com",
|
||||
});
|
||||
|
||||
const thread = presentation.resolve(commentThreadAnchorId);
|
||||
thread.addReply("Addressed in this revision.", { author: self });
|
||||
thread.resolve(self);
|
||||
|
||||
const notes = presentation.resolve(notesAnchorId);
|
||||
const existing = notes.text.trim();
|
||||
notes.text = [
|
||||
existing,
|
||||
"Opening: summarize the revised revenue outlook.",
|
||||
"Call out risk on enterprise timing.",
|
||||
].filter(Boolean).join("\n");
|
||||
notes.setVisible(true);
|
||||
|
||||
const verified = await presentation.inspect({
|
||||
kind: "thread,notes",
|
||||
target: { id: slideAnchorId, beforeLines: 1, afterLines: 4 },
|
||||
maxChars: 3000,
|
||||
});
|
||||
```
|
||||
|
||||
Keep unrelated threads and speaker notes intact unless the task explicitly asks
|
||||
to clear them.
|
||||
Generated
Vendored
+419
@@ -0,0 +1,419 @@
|
||||
# Presentation Layout Cookbook
|
||||
|
||||
First-principles recipes for arranging editable presentation JSX. These are
|
||||
layout mechanics, not deck archetypes.
|
||||
|
||||
Examples start after `presentation` and `slide` exist. Prefer string sizing
|
||||
(`"fill"`, `"hug"`) and local track values over helper imports.
|
||||
|
||||
Use `1280 x 720` as the default canvas unless the task or source deck requires
|
||||
another size:
|
||||
|
||||
```ts
|
||||
const SLIDE_W = 1280;
|
||||
const SLIDE_H = 720;
|
||||
const PAGE = { left: 72, top: 64, width: 1136, height: 592 };
|
||||
```
|
||||
|
||||
## Choose The Primitive
|
||||
|
||||
| Need | Use |
|
||||
| --- | --- |
|
||||
| Horizontal flow | `row` |
|
||||
| Vertical flow | `column` |
|
||||
| Column/row spans | `grid` |
|
||||
| Overlays or background plates | `layers` |
|
||||
| Surface plus child content | `box` |
|
||||
| Fixed placement on a slide | `slide.compose(node, { frame })` or facade `position` |
|
||||
|
||||
Use `frame` for the outer composed region. Inside the region, use `row`,
|
||||
`column`, `grid`, and `layers` so content stays resizable and inspectable. Use
|
||||
`layers` plus image `geometry`/`borderRadius` for overlays, scrims, and masked
|
||||
image compositions inside a region.
|
||||
|
||||
## Sizing Vocabulary
|
||||
|
||||
```tsx
|
||||
<box width="fill" height="fill" /> // claim available space
|
||||
<box width="hug" height="hug" /> // fit its children
|
||||
<box width={320} height={180} /> // fixed pixels
|
||||
```
|
||||
|
||||
Equal siblings fill equally:
|
||||
|
||||
```tsx
|
||||
<row width="fill" height={160} gap={24} align="stretch">
|
||||
<box width="fill" height="fill" className="bg-slate-50 rounded-xl" />
|
||||
<box width="fill" height="fill" className="bg-slate-50 rounded-xl" />
|
||||
<box width="fill" height="fill" className="bg-slate-50 rounded-xl" />
|
||||
</row>
|
||||
```
|
||||
|
||||
One fixed sibling plus one flexible sibling:
|
||||
|
||||
```tsx
|
||||
<row width="fill" height="fill" gap={32} align="stretch">
|
||||
<column width={360} height="fill" gap={16}>
|
||||
<paragraph className="text-slate-950 text-4xl font-bold">Fixed rail</paragraph>
|
||||
<paragraph className="text-slate-600 text-lg">This column stays 360px wide.</paragraph>
|
||||
</column>
|
||||
<box width="fill" height="fill" className="bg-slate-100 rounded-2xl" />
|
||||
</row>
|
||||
```
|
||||
|
||||
## Padding And Gutters
|
||||
|
||||
Use object padding for asymmetric page gutters. Use numeric padding for all
|
||||
sides.
|
||||
|
||||
Use an 8px spacing scale unless matching a source deck: common gaps are `16`,
|
||||
`24`, `28`, and `32`. Common page gutters use `PAGE`; pass `baseUnit: 8` to
|
||||
`slide.compose` when examples rely on this scale.
|
||||
|
||||
```tsx
|
||||
<column
|
||||
width="fill"
|
||||
height="fill"
|
||||
padding={{ top: 64, right: 80, bottom: 56, left: 80 }}
|
||||
gap={28}
|
||||
>
|
||||
<paragraph className="text-slate-950 text-5xl font-bold">Page title</paragraph>
|
||||
<box width="fill" height="fill" className="bg-white rounded-xl" />
|
||||
</column>
|
||||
```
|
||||
|
||||
```tsx
|
||||
<box width="fill" height="hug" padding={{ x: 28, y: 18 }} className="bg-sky-50 rounded-xl">
|
||||
<paragraph className="text-sky-950 text-xl font-bold">Compact padded box</paragraph>
|
||||
</box>
|
||||
```
|
||||
|
||||
## Rows
|
||||
|
||||
`row` lays out children left to right. `justify` distributes along the
|
||||
horizontal axis. `align` controls vertical alignment.
|
||||
|
||||
```tsx
|
||||
<row width="fill" height={72} align="center" justify="between">
|
||||
<paragraph className="text-slate-950 text-2xl font-bold">Left</paragraph>
|
||||
<paragraph className="text-slate-500 text-sm">Right</paragraph>
|
||||
</row>
|
||||
```
|
||||
|
||||
Center a child:
|
||||
|
||||
```tsx
|
||||
<row width="fill" height={220} align="center" justify="center">
|
||||
<box width={360} height={120} className="bg-white rounded-xl shadow-sm" />
|
||||
</row>
|
||||
```
|
||||
|
||||
Stretch all children to the row height:
|
||||
|
||||
```tsx
|
||||
<row width="fill" height={240} gap={20} align="stretch">
|
||||
<box width="fill" height="fill" className="bg-slate-50 rounded-xl" />
|
||||
<box width="fill" height="fill" className="bg-slate-50 rounded-xl" />
|
||||
</row>
|
||||
```
|
||||
|
||||
## Columns
|
||||
|
||||
`column` lays out children top to bottom. `justify` distributes along the
|
||||
vertical axis. `align` controls horizontal alignment.
|
||||
|
||||
```tsx
|
||||
<column width="fill" height="fill" justify="between" gap={24}>
|
||||
<paragraph className="text-slate-950 text-4xl font-bold">Top block</paragraph>
|
||||
<paragraph className="text-slate-600 text-lg">Bottom block</paragraph>
|
||||
</column>
|
||||
```
|
||||
|
||||
Metadata row, content region, and closing rule:
|
||||
|
||||
```tsx
|
||||
<column width="fill" height="fill" gap={24}>
|
||||
<row width="fill" height={72} align="center" justify="between">
|
||||
<paragraph className="text-slate-500 text-sm font-bold">HEADER</paragraph>
|
||||
<paragraph className="text-slate-400 text-sm">Source</paragraph>
|
||||
</row>
|
||||
<box width="fill" height="fill" className="bg-slate-50 rounded-xl" />
|
||||
<rule stroke="slate-200" weight={1} />
|
||||
</column>
|
||||
```
|
||||
|
||||
## Three Columns
|
||||
|
||||
Use a `row` when all columns are equal or only one side is fixed.
|
||||
|
||||
```tsx
|
||||
slide.compose(
|
||||
<row name="three-column-layout" width="fill" height="fill" gap={24} align="stretch">
|
||||
<column name="column-a" width="fill" height="fill" gap={12}>
|
||||
<paragraph className="text-slate-950 text-2xl font-bold">Column A</paragraph>
|
||||
<paragraph className="text-slate-600 text-base">Editable body copy.</paragraph>
|
||||
</column>
|
||||
<column name="column-b" width="fill" height="fill" gap={12}>
|
||||
<paragraph className="text-slate-950 text-2xl font-bold">Column B</paragraph>
|
||||
<paragraph className="text-slate-600 text-base">Editable body copy.</paragraph>
|
||||
</column>
|
||||
<column name="column-c" width="fill" height="fill" gap={12}>
|
||||
<paragraph className="text-slate-950 text-2xl font-bold">Column C</paragraph>
|
||||
<paragraph className="text-slate-600 text-base">Editable body copy.</paragraph>
|
||||
</column>
|
||||
</row>,
|
||||
{ frame: PAGE, baseUnit: 8 },
|
||||
);
|
||||
```
|
||||
|
||||
Use fixed rails when the center should absorb resize:
|
||||
|
||||
```tsx
|
||||
<row width="fill" height="fill" gap={24} align="stretch">
|
||||
<box width={240} height="fill" className="bg-slate-50 rounded-xl" />
|
||||
<box width="fill" height="fill" className="bg-white rounded-xl" />
|
||||
<box width={240} height="fill" className="bg-slate-50 rounded-xl" />
|
||||
</row>
|
||||
```
|
||||
|
||||
## Twelve-Column Grid
|
||||
|
||||
Use `grid` when child spans matter. Keep `fr` and fixed track objects local and
|
||||
obvious; use the literal `"auto"` for auto tracks:
|
||||
|
||||
```tsx
|
||||
const GRID_12 = Array.from(
|
||||
{ length: 12 },
|
||||
() => ({ mode: "fr", value: 1 }) as const,
|
||||
);
|
||||
```
|
||||
|
||||
Use a 12-column grid when spans communicate structure. Spans in a row usually
|
||||
add to 12, such as `4/4/4`, `3/6/3`, or `4/8`. Put vertical content inside
|
||||
`column` children and surfaces inside `box` children. Use a simple `row` when
|
||||
every column is equal and no span semantics are needed.
|
||||
|
||||
Full-width heading plus three equal columns:
|
||||
|
||||
```tsx
|
||||
<grid
|
||||
width="fill"
|
||||
height="fill"
|
||||
columns={GRID_12}
|
||||
rows={["auto", { mode: "fr", value: 1 }]}
|
||||
columnGap={24}
|
||||
rowGap={28}
|
||||
>
|
||||
<paragraph columnSpan={12} className="text-slate-950 text-5xl font-bold">
|
||||
Full-width heading
|
||||
</paragraph>
|
||||
<box columnSpan={4} width="fill" height="fill" className="bg-slate-50 rounded-xl" />
|
||||
<box columnSpan={4} width="fill" height="fill" className="bg-slate-50 rounded-xl" />
|
||||
<box columnSpan={4} width="fill" height="fill" className="bg-slate-50 rounded-xl" />
|
||||
</grid>
|
||||
```
|
||||
|
||||
Four/eight split:
|
||||
|
||||
```tsx
|
||||
<grid width="fill" height="fill" columns={GRID_12} columnGap={28}>
|
||||
<column columnSpan={4} width="fill" height="fill" gap={16}>
|
||||
<paragraph className="text-slate-950 text-4xl font-bold">Left span</paragraph>
|
||||
<paragraph className="text-slate-600 text-lg">Uses 4 of 12 columns.</paragraph>
|
||||
</column>
|
||||
<box columnSpan={8} width="fill" height="fill" className="bg-sky-50 rounded-2xl" />
|
||||
</grid>
|
||||
```
|
||||
|
||||
Three/six/three split:
|
||||
|
||||
```tsx
|
||||
<grid width="fill" height="fill" columns={GRID_12} columnGap={20}>
|
||||
<box columnSpan={3} width="fill" height="fill" className="bg-slate-50 rounded-xl" />
|
||||
<box columnSpan={6} width="fill" height="fill" className="bg-white rounded-xl shadow-sm" />
|
||||
<box columnSpan={3} width="fill" height="fill" className="bg-slate-50 rounded-xl" />
|
||||
</grid>
|
||||
```
|
||||
|
||||
Rows plus row spans:
|
||||
|
||||
```tsx
|
||||
<grid
|
||||
width="fill"
|
||||
height="fill"
|
||||
columns={GRID_12}
|
||||
rows={["auto", { mode: "fr", value: 1 }, { mode: "fr", value: 1 }]}
|
||||
columnGap={24}
|
||||
rowGap={24}
|
||||
>
|
||||
<paragraph columnSpan={12} className="text-slate-950 text-4xl font-bold">
|
||||
Heading
|
||||
</paragraph>
|
||||
<box columnSpan={8} rowSpan={2} width="fill" height="fill" className="bg-slate-50 rounded-xl" />
|
||||
<box columnSpan={4} width="fill" height="fill" className="bg-sky-50 rounded-xl" />
|
||||
<box columnSpan={4} width="fill" height="fill" className="bg-emerald-50 rounded-xl" />
|
||||
</grid>
|
||||
```
|
||||
|
||||
Mixed fixed and flexible tracks:
|
||||
|
||||
```tsx
|
||||
<grid
|
||||
width="fill"
|
||||
height="fill"
|
||||
columns={[
|
||||
{ mode: "fixed", value: 280 },
|
||||
{ mode: "fr", value: 1 },
|
||||
{ mode: "fixed", value: 220 },
|
||||
]}
|
||||
columnGap={24}
|
||||
>
|
||||
<box width="fill" height="fill" className="bg-slate-50 rounded-xl" />
|
||||
<box width="fill" height="fill" className="bg-white rounded-xl shadow-sm" />
|
||||
<box width="fill" height="fill" className="bg-slate-50 rounded-xl" />
|
||||
</grid>
|
||||
```
|
||||
|
||||
## Grid Alignment
|
||||
|
||||
Use `alignItems` and `justifyItems` for grid child alignment. If one child
|
||||
needs different alignment, wrap it in a `row`, `column`, or `box`.
|
||||
|
||||
| Node | Main axis | Cross axis | Distribution prop | Cross-axis prop | Defaults |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| `row` | horizontal | vertical | `justify`: `start`, `center`, `end`, `between` | `align`: `start`, `center`, `end`, `stretch` | `start` / `start` |
|
||||
| `column` | vertical | horizontal | `justify`: `start`, `center`, `end`, `between` | `align`: `start`, `center`, `end`, `stretch` | `start` / `start` |
|
||||
| `grid` | tracks | cells | `justifyItems`: `start`, `center`, `end`, `stretch` | `alignItems`: `start`, `center`, `end`, `stretch` | `stretch` / `stretch` |
|
||||
| `layers` | shared frame | shared frame | `justifyItems`: `start`, `center`, `end`, `stretch` | `alignItems`: `start`, `center`, `end`, `stretch` | `stretch` / `stretch` |
|
||||
|
||||
```tsx
|
||||
<grid
|
||||
width="fill"
|
||||
height={260}
|
||||
columns={[{ mode: "fr", value: 1 }, { mode: "fr", value: 1 }]}
|
||||
rows={[{ mode: "fr", value: 1 }]}
|
||||
columnGap={24}
|
||||
alignItems="center"
|
||||
justifyItems="stretch"
|
||||
>
|
||||
<box height={120} className="bg-slate-50 rounded-xl" />
|
||||
<box height="fill" className="bg-sky-50 rounded-xl" />
|
||||
</grid>
|
||||
```
|
||||
|
||||
## Layers
|
||||
|
||||
`layers` gives every child the same parent frame. Put visual backgrounds first,
|
||||
then overlays, then editable text.
|
||||
|
||||
```tsx
|
||||
<layers width="fill" height="fill">
|
||||
<image
|
||||
blob={backgroundBytes}
|
||||
contentType="image/jpeg"
|
||||
fit="cover"
|
||||
alt="Background"
|
||||
width="fill"
|
||||
height="fill"
|
||||
/>
|
||||
<shape geometry="rect" width="fill" height="fill" fill="black/45" />
|
||||
<column width={620} height="fill" padding={64} justify="end" gap={18}>
|
||||
<paragraph className="text-white text-5xl font-bold leading-tight">
|
||||
Editable headline
|
||||
</paragraph>
|
||||
<paragraph className="text-white/80 text-xl leading-relaxed">
|
||||
Editable supporting copy.
|
||||
</paragraph>
|
||||
</column>
|
||||
</layers>
|
||||
```
|
||||
|
||||
## Image Masks
|
||||
|
||||
Use image `geometry` for real clipping. Use `crop` plus `fit="cover"` when the
|
||||
subject should fill the mask.
|
||||
|
||||
Quick reference:
|
||||
|
||||
| Need | Use |
|
||||
| --- | --- |
|
||||
| Preserve the full image | `fit="contain"` |
|
||||
| Fill the frame and allow crop | `fit="cover"` |
|
||||
| Clip to a shape | `geometry="ellipse"` or `geometry="roundRect"` |
|
||||
| Rounded rectangle mask | `borderRadius="rounded-2xl"` |
|
||||
| Manual crop | `crop={{ left, top, right, bottom }}` with normalized `0..1` insets |
|
||||
|
||||
`crop` values are fractions removed from each source-image edge and are clamped.
|
||||
Overlays do not clip images; use image `geometry` or `borderRadius` for masks.
|
||||
|
||||
```tsx
|
||||
<image
|
||||
blob={portraitBytes}
|
||||
contentType="image/jpeg"
|
||||
alt="Portrait"
|
||||
geometry="ellipse"
|
||||
fit="cover"
|
||||
crop={{ left: 0.1, top: 0, right: 0.08, bottom: 0 }}
|
||||
width={240}
|
||||
height={240}
|
||||
/>
|
||||
```
|
||||
|
||||
Rounded rectangle image:
|
||||
|
||||
```tsx
|
||||
<image
|
||||
blob={photoBytes}
|
||||
contentType="image/jpeg"
|
||||
alt="Photo"
|
||||
fit="cover"
|
||||
width="fill"
|
||||
height={320}
|
||||
borderRadius="rounded-2xl"
|
||||
/>
|
||||
```
|
||||
|
||||
## Flow Versus Absolute Placement
|
||||
|
||||
Use flow for related content:
|
||||
|
||||
```tsx
|
||||
slide.compose(
|
||||
<column width="fill" height="fill" gap={20}>
|
||||
<paragraph className="text-slate-950 text-4xl font-bold">Title</paragraph>
|
||||
<row width="fill" height="fill" gap={24} align="stretch">
|
||||
<box width="fill" className="bg-slate-50 rounded-xl" />
|
||||
<box width="fill" className="bg-slate-50 rounded-xl" />
|
||||
</row>
|
||||
</column>,
|
||||
{ frame: PAGE, baseUnit: 8 },
|
||||
);
|
||||
```
|
||||
|
||||
Use absolute positions for elements that must land at exact slide coordinates:
|
||||
|
||||
```ts
|
||||
slide.shapes.add({
|
||||
geometry: "rect",
|
||||
name: "fixed-accent-bar",
|
||||
position: { left: 0, top: 0, width: 12, height: 720 },
|
||||
fill: "accent1",
|
||||
line: { style: "solid", fill: "none", width: 0 },
|
||||
});
|
||||
```
|
||||
|
||||
## Verify Layout
|
||||
|
||||
Inspect the layout tree when spans or wrapping matter:
|
||||
|
||||
```ts
|
||||
const layout = await slide.export({ format: "layout" });
|
||||
const png = await slide.export({ format: "png", scale: 1 });
|
||||
const snapshot = await presentation.inspect({
|
||||
kind: "slide,textbox,shape,image,table,chart",
|
||||
maxChars: 8000,
|
||||
});
|
||||
```
|
||||
|
||||
Check the rendered PNG for clipping, overlap, broken image crops, and text
|
||||
that should have stayed editable.
|
||||
Generated
Vendored
+201
@@ -0,0 +1,201 @@
|
||||
# Fill And Line Configs
|
||||
|
||||
Fill configs style shapes, chart regions, table cells, slide backgrounds, lines,
|
||||
and text fills. Text outlines use `LineConfig`, so their `fill`/`color` fields
|
||||
accept the same fill forms.
|
||||
|
||||
## Fill Forms
|
||||
|
||||
```ts
|
||||
shape.fill = fillConfig;
|
||||
shape.line = lineConfig;
|
||||
```
|
||||
|
||||
Supported fill forms:
|
||||
|
||||
- Theme, hex, RGB/RGBA, Tailwind-like color, and transformed color strings.
|
||||
- `"none"` and `"transparent"`.
|
||||
- Gradient strings such as `linear(...)` and `radial(...)`.
|
||||
- `{ type: "none" }`.
|
||||
- `{ type: "solid", color, pattern }`.
|
||||
- `{ type: "gradient", gradientKind, angleDeg, stops }`.
|
||||
- `{ type: "image", imageReference, srcRect, fillRect, stretchFillRect }`.
|
||||
|
||||
## String Fill Shortcuts
|
||||
|
||||
Use string fills for compact JSX and facade setters:
|
||||
|
||||
```tsx
|
||||
<shape geometry="rect" fill="none" line={{ style: "solid", fill: "slate-300", width: 1 }} />
|
||||
<box fill="black/45" />
|
||||
<box fill="transparent" />
|
||||
<box fill="accent1+18/90" />
|
||||
<box fill="linear(135deg, #ffffff 0%, sky-100 58%, #ffffff/0 100%)" />
|
||||
<shape geometry="ellipse" fill="radial(white/80 0%, emerald-200/45 48%, emerald-700/0 100%)" />
|
||||
```
|
||||
|
||||
Use `fill="none"` when the object should have no fill. Use
|
||||
`fill="transparent"` when the object should keep an editable transparent solid
|
||||
fill.
|
||||
|
||||
`+` lightens theme/RGB colors, `-` darkens, and `/` sets opacity. Tailwind-like
|
||||
color tokens, theme aliases, gradients, shadows, and text style strings are
|
||||
summarized in `tokens.md`.
|
||||
|
||||
## Fill Inline Types
|
||||
|
||||
```ts
|
||||
type ThemeColorName =
|
||||
| "accent1" | "accent2" | "accent3" | "accent4" | "accent5" | "accent6"
|
||||
| "bg1" | "bg2" | "tx1" | "tx2" | "dk1" | "lt1" | "dk2" | "lt2"
|
||||
| "hlink" | "folHlink";
|
||||
|
||||
type ColorConfig =
|
||||
| string
|
||||
| { type: "rgb"; value: string; transform?: ColorTransform }
|
||||
| { type: "theme"; value: ThemeColorName; transform?: ColorTransform };
|
||||
|
||||
type ColorTransform = {
|
||||
opacity?: number; // 0..1 or 0..100
|
||||
lighten?: number; // 0..1 or 0..100
|
||||
darken?: number; // 0..1 or 0..100
|
||||
};
|
||||
|
||||
type FillConfig =
|
||||
| string
|
||||
| { type: "none" }
|
||||
| { type: "solid"; color: ColorConfig; pattern?: PatternConfig }
|
||||
| {
|
||||
type: "gradient";
|
||||
stops: Array<{ offset: number; color: ColorConfig }>; // offset 0..100000
|
||||
offsetScale?: 1 | 100000;
|
||||
angleDeg?: number;
|
||||
gradientKind?: "linear" | "path";
|
||||
}
|
||||
| {
|
||||
type: "image";
|
||||
imageReference: { id: string };
|
||||
alphaModFix?: number;
|
||||
stretchFillRect?: { l?: number; t?: number; r?: number; b?: number };
|
||||
fillRect?: { l?: number; t?: number; r?: number; b?: number };
|
||||
srcRect?: { l?: number; t?: number; r?: number; b?: number };
|
||||
};
|
||||
```
|
||||
|
||||
## Gradient
|
||||
|
||||
```ts
|
||||
const fillConfig = {
|
||||
type: "gradient",
|
||||
gradientKind,
|
||||
angleDeg,
|
||||
stops: [
|
||||
{ offset: startOffset, color: startColor },
|
||||
{ offset: endOffset, color: endColor },
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
Gradient offsets use `0` to `100000`.
|
||||
|
||||
## Pattern Fills
|
||||
|
||||
Patterns are available through object fill configs:
|
||||
|
||||
```ts
|
||||
shape.fill = {
|
||||
type: "solid",
|
||||
color: "white",
|
||||
pattern: { type: "diagonalCross", color: "slate-300/70" },
|
||||
};
|
||||
```
|
||||
|
||||
Common compact pattern names:
|
||||
|
||||
```text
|
||||
percent10, percent20, lightHorizontal, lightVertical, smallGrid, dotGrid,
|
||||
diagonalCross, narrowVertical, wave, smallCheck
|
||||
```
|
||||
|
||||
Supported pattern names:
|
||||
|
||||
```text
|
||||
none, solid, mediumGray, darkGray, lightGray, darkHorizontal, darkVertical,
|
||||
darkDown, darkUp, darkGrid, darkTrellis, lightHorizontal, lightVertical,
|
||||
lightDown, lightUp, lightGrid, lightTrellis, gray125, gray0625, percent5,
|
||||
percent10, percent20, percent25, percent30, percent40, percent50, percent60,
|
||||
percent70, percent75, percent80, percent90, horizontal, vertical,
|
||||
narrowHorizontal, narrowVertical, dashedHorizontal, dashedVertical, cross,
|
||||
largeGrid, smallGrid, dotGrid, downwardDiagonal, upwardDiagonal,
|
||||
wideDownwardDiagonal, wideUpwardDiagonal, dashedDownwardDiagonal,
|
||||
dashedUpwardDiagonal, diagonalCross, smallCheck, largeCheck, smallConfetti,
|
||||
largeConfetti, horizontalBrick, diagonalBrick, solidDiamond, openDiamond,
|
||||
dottedDiamond, plaid, sphere, weave, divot, shingle, wave, trellis, zigZag
|
||||
```
|
||||
|
||||
## Line
|
||||
|
||||
```ts
|
||||
const lineConfig = {
|
||||
style: lineStyle,
|
||||
fill: lineFill,
|
||||
width: lineWidthPx,
|
||||
};
|
||||
```
|
||||
|
||||
## Line Inline Type
|
||||
|
||||
```ts
|
||||
type LineConfig = {
|
||||
style: "solid" | "dashed" | "dotted" | "dash-dot" | "dash-dot-dot" | string;
|
||||
fill?: FillConfig;
|
||||
width?: number;
|
||||
color?: FillConfig; // alias for fill
|
||||
weight?: number; // alias for width
|
||||
};
|
||||
```
|
||||
|
||||
## Cookbook
|
||||
|
||||
```ts
|
||||
// Linear background wash.
|
||||
slide.background.fill = "linear(0deg, #020617 0%, #2563eb 100%)";
|
||||
```
|
||||
|
||||
```ts
|
||||
// Soft radial spotlight behind a chart.
|
||||
chart.plotAreaFill = "radial(#dbeafe/90 0%, #ffffff/0 100%)";
|
||||
```
|
||||
|
||||
```ts
|
||||
// Exact gradient object.
|
||||
shape.fill = {
|
||||
type: "gradient",
|
||||
gradientKind: "linear",
|
||||
angleDeg: 35,
|
||||
offsetScale: 100000,
|
||||
stops: [
|
||||
{ offset: 0, color: "#ffffff" },
|
||||
{ offset: 100000, color: "sky-100" },
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
```ts
|
||||
// Normalized gradient offsets.
|
||||
shape.fill = {
|
||||
type: "gradient",
|
||||
gradientKind: "linear",
|
||||
offsetScale: 1,
|
||||
stops: [
|
||||
{ offset: 0, color: "#ffffff" },
|
||||
{ offset: 1, color: "sky-100" },
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
```ts
|
||||
// Hairline rule and muted border.
|
||||
shape.line = { style: "solid", fill: "slate-200", width: 1 };
|
||||
ruleShape.line = { style: "dashed", fill: "#94a3b8", width: 1 };
|
||||
```
|
||||
Generated
Vendored
+223
@@ -0,0 +1,223 @@
|
||||
# Help
|
||||
|
||||
Use `presentation.help(...)` to search the presentation JS API and template
|
||||
catalog. Help emits bounded NDJSON records for quick lookup during create, edit,
|
||||
and review workflows.
|
||||
|
||||
## Query
|
||||
|
||||
```ts
|
||||
const result = presentation.help(query, {
|
||||
search,
|
||||
include,
|
||||
maxChars,
|
||||
});
|
||||
console.log(result.ndjson);
|
||||
```
|
||||
|
||||
Example output for `query = "*"` with `include = ["index", "examples"]`:
|
||||
|
||||
```text
|
||||
{"kind":"api","name":"presentation.help","summary":"Search the presentation JS API and template catalog.","tags":["help","docs","examples","presentation.help"],"examples":[{"summary":"Find shape editing APIs","code":"const result = presentation.help('*', {\n search: 'slide.shapes.delete|shape.delete|slide.shapes.add|deleteAll',\n include: ['index', 'examples', 'notes'],\n maxChars: 12000,\n});\nconsole.log(result.ndjson);"}]}
|
||||
{"kind":"api","name":"slide.shapes.add","summary":"Add a preset/custom/connector shape to a slide.","tags":["shape","shapes.add","rectangle","ellipse","connector","slide.shapes.add"],"examples":[{"summary":"Create a styled rectangle","code":"const shape = slide.shapes.add({\n geometry: 'roundRect',\n position: { left: 72, top: 96, width: 320, height: 120 },\n fill: { type: 'solid', color: 'accent1' },\n line: { style: 'solid', fill: 'accent2', width: 2 },\n});\nshape.text = 'Launch plan';"}]}
|
||||
{"kind":"template","name":"agenda","summary":"Agenda slide with a title and list body.","examples":[{"summary":"Apply the agenda template","code":"presentation.apply(presentation.template('agenda'));"}]}
|
||||
```
|
||||
|
||||
Use API records to find facade names and examples; use template records with
|
||||
`presentation.template(name)`.
|
||||
|
||||
Common queries:
|
||||
|
||||
```text
|
||||
*, shape*, slide.shapes.add, chart xAxis, template*
|
||||
```
|
||||
|
||||
Query behavior:
|
||||
|
||||
```text
|
||||
* lists all matching API and template records
|
||||
shape* uses glob matching
|
||||
slide.shapes.add matches the exact dotted API name
|
||||
chart xAxis matches entries containing either word token
|
||||
template* lists template records only
|
||||
```
|
||||
|
||||
Use `search` as a case-insensitive regular expression over the JSON lines after
|
||||
the primary query has selected records:
|
||||
|
||||
```ts
|
||||
const focused = presentation.help("*", {
|
||||
search:
|
||||
"slide\\.shapes\\.delete|shape\\.delete|slide\\.shapes\\.add|deleteAll",
|
||||
include: ["index", "examples", "notes"],
|
||||
maxChars: 12000,
|
||||
});
|
||||
console.log(focused.ndjson);
|
||||
```
|
||||
|
||||
## Include
|
||||
|
||||
Default output includes index fields such as:
|
||||
|
||||
```text
|
||||
kind, name, summary, tags
|
||||
```
|
||||
|
||||
Useful include tokens:
|
||||
|
||||
```text
|
||||
index, examples, notes
|
||||
```
|
||||
|
||||
`include` accepts either an array or a comma-separated string:
|
||||
|
||||
```ts
|
||||
const shapeExamples = presentation.help("slide.shapes.add", {
|
||||
include: ["examples", "notes"],
|
||||
});
|
||||
|
||||
const templateExamples = presentation.help("template*", {
|
||||
include: "index,examples",
|
||||
});
|
||||
```
|
||||
|
||||
## Inline Type
|
||||
|
||||
```ts
|
||||
type PresentationHelpOptions = {
|
||||
include?: string[] | string;
|
||||
search?: string;
|
||||
maxChars?: number;
|
||||
};
|
||||
|
||||
type PresentationHelpResult = {
|
||||
ndjson: string;
|
||||
truncated: boolean;
|
||||
metadata: {
|
||||
revision: string;
|
||||
query: string;
|
||||
include: {
|
||||
requested?: string[] | string;
|
||||
tokens: string[];
|
||||
};
|
||||
search?: string;
|
||||
notices?: string[];
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
## Record Kinds
|
||||
|
||||
API records describe public JS facades and methods:
|
||||
|
||||
```text
|
||||
{"kind":"api","name":"slide.shapes.add","summary":"Add a preset/custom/connector shape to a slide.","tags":["shape","shapes.add","rectangle","ellipse","connector","slide.shapes.add"]}
|
||||
{"kind":"api","name":"shape.delete","summary":"Delete this shape from its slide.","tags":["shape","delete shape","remove shape","shape.delete"]}
|
||||
```
|
||||
|
||||
When examples are included, records focus on usage snippets:
|
||||
|
||||
```text
|
||||
{"kind":"api","name":"slide.shapes.add","examples":[{"summary":"Create a styled rectangle","code":"const shape = slide.shapes.add({\n geometry: 'roundRect',\n position: { left: 72, top: 96, width: 320, height: 120 },\n fill: { type: 'solid', color: 'accent1' },\n line: { style: 'solid', fill: 'accent2', width: 2 },\n});\nshape.text = 'Launch plan';"}],"notes":["Preset geometry values include rect, roundRect, ellipse, triangle, rightArrow, and many other PowerPoint shape names."]}
|
||||
```
|
||||
|
||||
Template records describe named template patches for
|
||||
`presentation.template(name)`:
|
||||
|
||||
```text
|
||||
{"kind":"template","name":"title-slide","summary":"Title + subtitle slide with centered text boxes."}
|
||||
{"kind":"template","name":"two-up","summary":"Two-column slide with left/right content boxes."}
|
||||
{"kind":"template","name":"agenda","summary":"Agenda slide with a title and list body."}
|
||||
```
|
||||
|
||||
If output exceeds `maxChars`, the final line is a notice record and
|
||||
`result.truncated` is `true`:
|
||||
|
||||
```text
|
||||
{"kind":"notice","message":"Truncated: omitted 93 lines. Increase maxChars or narrow query."}
|
||||
```
|
||||
|
||||
## Create/Edit Loop
|
||||
|
||||
```ts
|
||||
// Find the public API surface for the edit.
|
||||
const shapeHelp = presentation.help("shape*", {
|
||||
include: ["index", "examples", "notes"],
|
||||
maxChars: 8000,
|
||||
});
|
||||
|
||||
// Build with the documented JS facade.
|
||||
const slide = presentation.slides.add();
|
||||
const shape = slide.shapes.add({
|
||||
geometry: "roundRect",
|
||||
position: { left: 72, top: 96, width: 320, height: 120 },
|
||||
fill: { type: "solid", color: "accent1" },
|
||||
});
|
||||
shape.text = "Launch plan";
|
||||
|
||||
// Inspect the live deck after editing.
|
||||
const snapshot = await presentation.inspect({
|
||||
kind: "slide,textbox,shape",
|
||||
maxChars: 4000,
|
||||
});
|
||||
```
|
||||
|
||||
## Imported Templates
|
||||
|
||||
```ts
|
||||
const templates = presentation.help("template*", {
|
||||
include: ["index", "examples"],
|
||||
maxChars: 4000,
|
||||
});
|
||||
|
||||
presentation.apply(presentation.template("agenda"));
|
||||
```
|
||||
|
||||
Use template help to discover the available names before calling
|
||||
`presentation.template(name)`.
|
||||
|
||||
## Cookbook
|
||||
|
||||
```ts
|
||||
// List the top-level deck APIs.
|
||||
const deckApis = presentation.help("presentation*", {
|
||||
include: "index",
|
||||
maxChars: 6000,
|
||||
});
|
||||
```
|
||||
|
||||
```ts
|
||||
// Search broadly, then filter by regex.
|
||||
const hits = presentation.help("*", {
|
||||
search: "chart|axis|legend",
|
||||
include: ["index", "examples"],
|
||||
maxChars: 8000,
|
||||
});
|
||||
```
|
||||
|
||||
```ts
|
||||
// Pull examples for one exact API.
|
||||
const examples = presentation.help("slide.charts.add", {
|
||||
include: ["examples", "notes"],
|
||||
maxChars: 4000,
|
||||
});
|
||||
```
|
||||
|
||||
```ts
|
||||
// Pair help with inspect for focused edits.
|
||||
const help = presentation.help("shape.text.replace", {
|
||||
include: ["examples", "notes"],
|
||||
});
|
||||
const before = await presentation.inspect({
|
||||
kind: "textbox,shape",
|
||||
search: "Placeholder",
|
||||
maxChars: 4000,
|
||||
});
|
||||
const target = presentation.resolve(anchorId);
|
||||
target.text.replace("Placeholder", "Updated text");
|
||||
const after = await presentation.inspect({
|
||||
target: { id: anchorId, beforeLines: 2, afterLines: 2 },
|
||||
kind: "textbox,shape",
|
||||
maxChars: 2000,
|
||||
});
|
||||
```
|
||||
Generated
Vendored
+286
@@ -0,0 +1,286 @@
|
||||
# Images
|
||||
|
||||
`slide.images` inserts image elements from local paths, bytes, data URLs, SVG, and prompts.
|
||||
|
||||
For embedded image output, use `blob={imageBytes}` with `contentType`. Download remote images
|
||||
first, then pass their local `path` or embedded `blob` bytes to `add` or `replace`.
|
||||
HTTP(S) sources are rejected without fetching them.
|
||||
|
||||
## Add Image
|
||||
|
||||
```ts
|
||||
const image = slide.images.add({
|
||||
blob: imageBytes,
|
||||
contentType: "image/png",
|
||||
alt: "Product screenshot",
|
||||
fit: "cover",
|
||||
position: { left: 72, top: 120, width: 520, height: 320 },
|
||||
crop: { left: 0.02, top: 0, right: 0.04, bottom: 0 },
|
||||
geometry: "roundRect",
|
||||
borderRadius: "rounded-2xl",
|
||||
});
|
||||
```
|
||||
|
||||
## Path Reference And Inline SVG
|
||||
|
||||
```ts
|
||||
const localImage = slide.images.add({
|
||||
path: "/absolute/path/to/product.png",
|
||||
alt: "Product screenshot from disk",
|
||||
fit: "cover",
|
||||
position: { left: 72, top: 120, width: 520, height: 320 },
|
||||
});
|
||||
|
||||
const icon = slide.images.add({
|
||||
svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><circle cx="12" cy="12" r="10" fill="#2563eb"/></svg>',
|
||||
alt: "Blue status icon",
|
||||
position: { left: 620, top: 120, width: 48, height: 48 },
|
||||
});
|
||||
```
|
||||
|
||||
## Image Inline Types
|
||||
|
||||
```ts
|
||||
type ImageSource =
|
||||
| { path: string; prompt?: string }
|
||||
| { svg: string; prompt?: string }
|
||||
| { blob: ArrayBuffer | Uint8Array; prompt?: string }
|
||||
| { dataUrl: string; prompt?: string }
|
||||
| { prompt: string };
|
||||
|
||||
type ImageAddOptions = ImageSource & {
|
||||
alt?: string;
|
||||
fit?: "contain" | "cover";
|
||||
contentType?: string;
|
||||
position?: { left?: number; top?: number; width?: number; height?: number };
|
||||
frame?: { left?: number; top?: number; width?: number; height?: number };
|
||||
crop?: { left: number | string; top: number | string; right: number | string; bottom: number | string };
|
||||
geometry?: string; // common: "rect", "roundRect", "ellipse"; full list is the shape preset list
|
||||
borderRadius?: number | string; // number = pixels; string = supported rounded-* token
|
||||
};
|
||||
```
|
||||
|
||||
`position` and `frame` use the same pixel shape. Use either spelling; prefer
|
||||
`position` in add calls and `frame` when preserving imported placement.
|
||||
|
||||
## Resolved From Inspect
|
||||
|
||||
```ts
|
||||
const image = presentation.resolve("im/c3d4e5f6");
|
||||
const oldFrame = image.frame;
|
||||
const oldCrop = image.crop;
|
||||
const oldFit = image.fit;
|
||||
const oldAlt = image.alt;
|
||||
const oldPrompt = image.prompt;
|
||||
const oldGeometry = image.geometry;
|
||||
const oldBorderRadius = image.borderRadius;
|
||||
const oldRotation = image.rotation;
|
||||
const oldFlipHorizontal = image.flipHorizontal;
|
||||
const oldFlipVertical = image.flipVertical;
|
||||
const oldLockAspectRatio = image.lockAspectRatio;
|
||||
|
||||
image.replace({
|
||||
blob: nextBytes,
|
||||
contentType: "image/png",
|
||||
alt: oldAlt ?? "Updated screenshot",
|
||||
...(oldFit ? { fit: oldFit } : {}),
|
||||
...(oldPrompt ? { prompt: oldPrompt } : {}),
|
||||
});
|
||||
image.frame = oldFrame;
|
||||
image.crop = oldCrop;
|
||||
image.geometry = oldGeometry;
|
||||
image.borderRadius = oldBorderRadius;
|
||||
image.rotation = oldRotation;
|
||||
image.flipHorizontal = oldFlipHorizontal;
|
||||
image.flipVertical = oldFlipVertical;
|
||||
image.lockAspectRatio = oldLockAspectRatio;
|
||||
```
|
||||
|
||||
Use `presentation.inspect({ kind: "image", search })` to find the `im/...`
|
||||
anchor id. Preserve frame, crop, fit, alt text, mask geometry, and border radius
|
||||
unless the edit explicitly changes them.
|
||||
Concrete source replacements produce concrete images; pass `prompt` when it
|
||||
should remain available as regeneration metadata.
|
||||
|
||||
## Edit Placement And Fit
|
||||
|
||||
```ts
|
||||
image.position = position;
|
||||
image.frame = frame;
|
||||
image.fit = fit;
|
||||
image.crop = crop;
|
||||
image.geometry = "roundRect";
|
||||
image.borderRadius = "rounded-xl";
|
||||
image.rotation = rotationDeg;
|
||||
image.flipHorizontal = flipHorizontal;
|
||||
image.flipVertical = flipVertical;
|
||||
image.lockAspectRatio = true;
|
||||
image.width = 320;
|
||||
image.height = 180;
|
||||
image.alt = altText;
|
||||
```
|
||||
|
||||
`crop` supplies all four edges. Numbers are normalized `0..1` fractions removed
|
||||
from the source image; strings accept percentages such as `"10%"` or pixel
|
||||
insets such as `"24px"` when source dimensions are available. Values are clamped.
|
||||
`fit="cover"` fills the frame and may crop; `fit="contain"`
|
||||
preserves the full image. `geometry="ellipse"` or `geometry="roundRect"` clips
|
||||
the image. `borderRadius` is for rect/roundRect masks; numbers are pixels and
|
||||
strings use supported `rounded-*` tokens.
|
||||
|
||||
## Replace Source
|
||||
|
||||
```ts
|
||||
image.replace({
|
||||
blob,
|
||||
contentType,
|
||||
path,
|
||||
svg,
|
||||
dataUrl,
|
||||
prompt,
|
||||
alt,
|
||||
fit,
|
||||
});
|
||||
```
|
||||
|
||||
`replace` swaps the source and common source metadata. Choose one primary source
|
||||
field as with `add`. Preserve or set placement, crop, mask geometry, and border
|
||||
radius on the image facade itself.
|
||||
|
||||
## Replace And Regenerate Inline Types
|
||||
|
||||
```ts
|
||||
type ImageReplaceOptions = {
|
||||
alt?: string;
|
||||
fit?: "contain" | "cover";
|
||||
contentType?: string;
|
||||
path?: string;
|
||||
svg?: string;
|
||||
blob?: ArrayBuffer | Uint8Array;
|
||||
dataUrl?: string;
|
||||
prompt?: string;
|
||||
};
|
||||
|
||||
type ImageRegenerateOptions = {
|
||||
prompt?: string;
|
||||
kind?: "sticker" | "layout" | "content" | "infographic";
|
||||
fit?: "contain" | "cover";
|
||||
size?: "1024x1024" | "1536x1024" | "1024x1536";
|
||||
quality?: "low" | "medium" | "high";
|
||||
background?: "auto" | "transparent" | "opaque";
|
||||
outputFormat?: "png" | "jpeg" | "webp";
|
||||
};
|
||||
```
|
||||
|
||||
## Prompt Images
|
||||
|
||||
```ts
|
||||
const promptImage = slide.images.add({
|
||||
prompt,
|
||||
alt,
|
||||
position,
|
||||
fit,
|
||||
});
|
||||
|
||||
promptImage.regenerate({ kind });
|
||||
```
|
||||
|
||||
Prompt placeholders are optional. Use concrete sources when asset bytes or
|
||||
references are already available.
|
||||
|
||||
## Concrete Image Sources
|
||||
|
||||
```ts
|
||||
const imageBytes = assetBytes;
|
||||
const imageUri = assetUri;
|
||||
const imageDataUrl = assetDataUrl;
|
||||
```
|
||||
|
||||
## JSX Declarative Image
|
||||
|
||||
```tsx
|
||||
/** @jsxRuntime automatic */
|
||||
|
||||
slide.compose(
|
||||
<row width="fill" height="fill" gap={16}>
|
||||
<image
|
||||
blob={imageBytes}
|
||||
alt="Embedded bytes"
|
||||
fit="cover"
|
||||
width={320}
|
||||
height={180}
|
||||
/>
|
||||
<image
|
||||
path={imagePath}
|
||||
alt="Local image"
|
||||
fit="contain"
|
||||
width={320}
|
||||
height={180}
|
||||
/>
|
||||
</row>,
|
||||
{
|
||||
frame: { left: 48, top: 40, width: 864, height: 240 },
|
||||
baseUnit: 8,
|
||||
},
|
||||
);
|
||||
```
|
||||
|
||||
## Cookbook
|
||||
|
||||
```ts
|
||||
// Full-frame image crop.
|
||||
slide.images.add({
|
||||
blob: imageBytes,
|
||||
contentType: "image/jpeg",
|
||||
alt: "Workspace image",
|
||||
fit: "cover",
|
||||
position: { left: 0, top: 0, width: 1280, height: 720 },
|
||||
});
|
||||
```
|
||||
|
||||
```ts
|
||||
// Rounded image mask.
|
||||
slide.images.add({
|
||||
blob: imageBytes,
|
||||
contentType: "image/jpeg",
|
||||
alt: "Customer interview",
|
||||
fit: "cover",
|
||||
geometry: "roundRect",
|
||||
borderRadius: "rounded-3xl",
|
||||
position: { left: 720, top: 96, width: 448, height: 512 },
|
||||
});
|
||||
```
|
||||
|
||||
```tsx
|
||||
// Circular avatar mask in JSX.
|
||||
<image
|
||||
blob={avatarBytes}
|
||||
contentType="image/png"
|
||||
alt="Speaker"
|
||||
fit="cover"
|
||||
geometry="ellipse"
|
||||
width={96}
|
||||
height={96}
|
||||
/>
|
||||
```
|
||||
|
||||
```tsx
|
||||
// Rounded crop/mask in JSX.
|
||||
<image
|
||||
blob={portraitBytes}
|
||||
contentType="image/jpeg"
|
||||
alt="Customer portrait"
|
||||
fit="cover"
|
||||
geometry="roundRect"
|
||||
borderRadius="rounded-2xl"
|
||||
crop={{ left: 0.08, top: 0.02, right: 0.14, bottom: 0 }}
|
||||
width={320}
|
||||
height={420}
|
||||
/>
|
||||
```
|
||||
|
||||
```ts
|
||||
// Manual crop when the subject is off-center.
|
||||
image.fit = "cover";
|
||||
image.crop = { left: 0.08, top: 0.02, right: 0.18, bottom: 0.06 };
|
||||
```
|
||||
Generated
Vendored
+131
@@ -0,0 +1,131 @@
|
||||
# Inspect
|
||||
|
||||
`presentation.inspect({ select, include, fileName })` queries one public
|
||||
presentation tree with [RFC 9535 JSONPath](https://www.rfc-editor.org/rfc/rfc9535.html).
|
||||
The [JSON Schema](./inspect.schema.json) describes its content and layout fields.
|
||||
`select` finds nodes; `include` chooses exact fields from those nodes.
|
||||
|
||||
## Read content
|
||||
|
||||
```ts
|
||||
await presentation.inspect({
|
||||
select: "$.slides[*]",
|
||||
include: [
|
||||
"id", "index", "layout", "title",
|
||||
"elements.id", "elements.kind", "elements.text", "elements.alt", "elements.title",
|
||||
"notes.text",
|
||||
],
|
||||
fileName: "content.ndjson",
|
||||
});
|
||||
```
|
||||
|
||||
This writes one slide per line, retaining its applied layout and editable
|
||||
element IDs. Text includes paragraph breaks and complete table content. The
|
||||
query omits positions and styles, so those fields are not computed.
|
||||
|
||||
The tree has this shape (selected fields):
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "openai.presentation.inspection/v1",
|
||||
"unit": "px",
|
||||
"id": "pr/abcdefgh",
|
||||
"kind": "presentation",
|
||||
"slides": [{
|
||||
"id": "sl/12345678", "kind": "slide", "index": 0,
|
||||
"layout": { "id": "ly/abcdefgh", "name": "Title and image" },
|
||||
"elements": [{ "id": "sh/abcdefgh", "kind": "textbox", "text": "Welcome" }],
|
||||
"notes": { "id": "nt/12345678", "kind": "notes", "text": "Opening remarks" }
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
Only canonical prefix/hash IDs are exposed. Pass editable `sl/`, `sh/`, `im/`,
|
||||
`ch/`, `tb/`, `ea/`, and `nt/` IDs to `presentation.resolve(id)`.
|
||||
The read-only `ly/` ID identifies the applied layout. `index` is zero-based;
|
||||
positions and computed font sizes use pixels.
|
||||
|
||||
## Find and edit
|
||||
|
||||
```ts
|
||||
const hits = await presentation.inspect({
|
||||
select: "$.slides[*].elements[?(@.text == 'Confidential')]",
|
||||
include: ["id", "text"],
|
||||
});
|
||||
```
|
||||
|
||||
JSONPath filters inspect source fields before projection. Comparisons therefore
|
||||
match the text itself, rather than its serialized JSON representation. Use
|
||||
`$.slides[0,2].elements[*]` for two slides or a predicate such as
|
||||
`@.kind == 'image'` for one element kind. Selected scalar values are also valid;
|
||||
for example, `$.slides[*].title` returns title strings.
|
||||
|
||||
Use `search(@.text, 'overview|steps')` for a text pattern, or `match()` to match
|
||||
the entire string. Patterns follow [I-Regexp](https://www.rfc-editor.org/rfc/rfc9485.html).
|
||||
`length()` measures a value, `count()` counts selected nodes, and `value()`
|
||||
extracts a value when a query selects exactly one node. Filters use `==` and
|
||||
`!=`; JavaScript expressions and method calls are not part of JSONPath.
|
||||
Repeated selectors retain repeated results: `$.slides[0,0]` selects slide zero
|
||||
twice. Invalid queries report a syntax error with the character offset.
|
||||
|
||||
Use the literal ID from the result for subsequent edits. Read computed styling
|
||||
or mixed-format text for that same ID:
|
||||
|
||||
```ts
|
||||
await presentation.inspect({
|
||||
select: "$.slides[*].elements[?(@.id == 'sh/abcdefgh')]",
|
||||
include: ["id", "text", "position", "style", "paragraphs"],
|
||||
});
|
||||
```
|
||||
|
||||
`style` reflects theme and inherited formatting. `paragraphs` preserves styled
|
||||
runs; `cells` expands a table. These fields are evaluated when accessed without
|
||||
rendering slides or fetching images. Explicit paths keep queries focused;
|
||||
recursive `..` queries can traverse computed fields across the document.
|
||||
|
||||
`include` is an exact array of typed field paths. Nested paths such as
|
||||
`elements.text` preserve arrays and object structure. Including a parent such
|
||||
as `style` includes that complete object. Omitting `include` returns complete
|
||||
selected nodes. Include `id` explicitly when the next step needs an editing ID.
|
||||
|
||||
## Files and results
|
||||
|
||||
An attached Artifact Session writes all selected records to
|
||||
`<outputDirectory>/presentation-inspect.ndjson`. `fileName` chooses another
|
||||
NDJSON basename. Reusing a name replaces that file. The completed session run's
|
||||
`files` contains finalized paths. Unnamed inspection outside a session stays in
|
||||
memory; the Node runtime supports a named standalone output path.
|
||||
|
||||
The returned object prints `recordCount` and output metadata. Access `.records`
|
||||
or `.ndjson` explicitly for the complete values. No pagination or record
|
||||
abbreviation applies to JSONPath queries. Select nodes and fields according to
|
||||
the task before reading the output into model context.
|
||||
|
||||
Rendering separately writes `slide-N.png` and `slide-N.layout.json`. Layout
|
||||
files use these same element fields and canonical IDs in a slide-scoped file
|
||||
envelope. The file's `slide` contains the inspected slide metadata and its
|
||||
`elements` contains the compact layout field selection. The content query does
|
||||
not replace those render outputs. Full layout export also exposes inherited
|
||||
paint layers and paragraph/run formatting.
|
||||
|
||||
## Types
|
||||
|
||||
```ts
|
||||
type PresentationInspectQueryOptions = {
|
||||
select: string;
|
||||
include?: readonly PresentationInspectField[];
|
||||
fileName?: string;
|
||||
};
|
||||
|
||||
type PresentationInspectQueryResult = {
|
||||
readonly records: readonly unknown[];
|
||||
readonly recordCount: number;
|
||||
readonly ndjson: string;
|
||||
readonly path?: string;
|
||||
readonly status?: "pending" | "saved" | "conflict" | "error";
|
||||
readonly message?: string;
|
||||
};
|
||||
```
|
||||
|
||||
The earlier preset and record-filter overloads remain deprecated compatibility
|
||||
entry points. New callers should use the explicit query above.
|
||||
Generated
Vendored
+865
@@ -0,0 +1,865 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"schema": {
|
||||
"type": "string",
|
||||
"const": "openai.presentation.inspection/v1"
|
||||
},
|
||||
"unit": {
|
||||
"type": "string",
|
||||
"const": "px"
|
||||
},
|
||||
"id": {
|
||||
"type": "string",
|
||||
"pattern": "^pr\\/[a-z0-9]+$"
|
||||
},
|
||||
"kind": {
|
||||
"type": "string",
|
||||
"const": "presentation"
|
||||
},
|
||||
"slides": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/$defs/Slide"
|
||||
}
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"schema",
|
||||
"unit",
|
||||
"id",
|
||||
"kind",
|
||||
"slides"
|
||||
],
|
||||
"additionalProperties": false,
|
||||
"$defs": {
|
||||
"Slide": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"pattern": "^sl\\/[a-z0-9]+$"
|
||||
},
|
||||
"kind": {
|
||||
"type": "string",
|
||||
"const": "slide"
|
||||
},
|
||||
"index": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 9007199254740991
|
||||
},
|
||||
"layout": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"pattern": "^ly\\/[a-z0-9]+$"
|
||||
},
|
||||
"name": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"id"
|
||||
],
|
||||
"additionalProperties": false
|
||||
},
|
||||
"title": {
|
||||
"type": "string"
|
||||
},
|
||||
"position": {
|
||||
"$ref": "#/$defs/Position"
|
||||
},
|
||||
"backgroundColor": {
|
||||
"$ref": "#/$defs/Color"
|
||||
},
|
||||
"elements": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/$defs/Element"
|
||||
}
|
||||
},
|
||||
"notes": {
|
||||
"$ref": "#/$defs/Notes"
|
||||
},
|
||||
"inheritedLayers": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/$defs/InheritedLayer"
|
||||
}
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"id",
|
||||
"kind",
|
||||
"index",
|
||||
"position",
|
||||
"elements"
|
||||
],
|
||||
"additionalProperties": false,
|
||||
"id": "Slide"
|
||||
},
|
||||
"Position": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"left": {
|
||||
"type": "number"
|
||||
},
|
||||
"top": {
|
||||
"type": "number"
|
||||
},
|
||||
"width": {
|
||||
"type": "number"
|
||||
},
|
||||
"height": {
|
||||
"type": "number"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"left",
|
||||
"top",
|
||||
"width",
|
||||
"height"
|
||||
],
|
||||
"additionalProperties": false,
|
||||
"id": "Position"
|
||||
},
|
||||
"Color": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"type": {
|
||||
"type": "string",
|
||||
"const": "rgb"
|
||||
},
|
||||
"value": {
|
||||
"type": "string"
|
||||
},
|
||||
"transform": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"opacity": {
|
||||
"type": "number"
|
||||
},
|
||||
"lighten": {
|
||||
"type": "number"
|
||||
},
|
||||
"darken": {
|
||||
"type": "number"
|
||||
}
|
||||
},
|
||||
"additionalProperties": false
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"type",
|
||||
"value"
|
||||
],
|
||||
"additionalProperties": false
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"type": {
|
||||
"type": "string",
|
||||
"const": "theme"
|
||||
},
|
||||
"value": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"accent1",
|
||||
"accent2",
|
||||
"accent3",
|
||||
"accent4",
|
||||
"accent5",
|
||||
"accent6",
|
||||
"bg1",
|
||||
"bg2",
|
||||
"tx1",
|
||||
"tx2",
|
||||
"dk1",
|
||||
"lt1",
|
||||
"dk2",
|
||||
"lt2",
|
||||
"hlink",
|
||||
"folHlink"
|
||||
]
|
||||
},
|
||||
"transform": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"opacity": {
|
||||
"type": "number"
|
||||
},
|
||||
"lighten": {
|
||||
"type": "number"
|
||||
},
|
||||
"darken": {
|
||||
"type": "number"
|
||||
}
|
||||
},
|
||||
"additionalProperties": false
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"type",
|
||||
"value"
|
||||
],
|
||||
"additionalProperties": false
|
||||
}
|
||||
],
|
||||
"id": "Color"
|
||||
},
|
||||
"Element": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"pattern": "^(sh|im|ch|tb|ea)\\/[a-z0-9]+$"
|
||||
},
|
||||
"kind": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"shape",
|
||||
"textbox",
|
||||
"image",
|
||||
"chart",
|
||||
"table",
|
||||
"embeddedArtifact"
|
||||
]
|
||||
},
|
||||
"name": {
|
||||
"type": "string"
|
||||
},
|
||||
"text": {
|
||||
"type": "string"
|
||||
},
|
||||
"title": {
|
||||
"type": "string"
|
||||
},
|
||||
"position": {
|
||||
"$ref": "#/$defs/Position"
|
||||
},
|
||||
"order": {
|
||||
"type": "integer",
|
||||
"exclusiveMinimum": 0,
|
||||
"maximum": 9007199254740991
|
||||
},
|
||||
"scope": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"slide",
|
||||
"layout",
|
||||
"master"
|
||||
]
|
||||
},
|
||||
"editable": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"rotation": {
|
||||
"type": "number"
|
||||
},
|
||||
"horizontalFlip": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"verticalFlip": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"hidden": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"geometry": {
|
||||
"type": "string"
|
||||
},
|
||||
"style": {
|
||||
"$ref": "#/$defs/TextStyle"
|
||||
},
|
||||
"paragraphs": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/$defs/Paragraph"
|
||||
}
|
||||
},
|
||||
"fillColor": {
|
||||
"$ref": "#/$defs/Color"
|
||||
},
|
||||
"lineColor": {
|
||||
"$ref": "#/$defs/Color"
|
||||
},
|
||||
"lineWidth": {
|
||||
"type": "number"
|
||||
},
|
||||
"alt": {
|
||||
"type": "string"
|
||||
},
|
||||
"chartType": {
|
||||
"type": "string"
|
||||
},
|
||||
"rows": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 9007199254740991
|
||||
},
|
||||
"cols": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 9007199254740991
|
||||
},
|
||||
"contentType": {
|
||||
"type": "string"
|
||||
},
|
||||
"crop": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"left": {
|
||||
"type": "number"
|
||||
},
|
||||
"top": {
|
||||
"type": "number"
|
||||
},
|
||||
"right": {
|
||||
"type": "number"
|
||||
},
|
||||
"bottom": {
|
||||
"type": "number"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"left",
|
||||
"top",
|
||||
"right",
|
||||
"bottom"
|
||||
],
|
||||
"additionalProperties": false
|
||||
},
|
||||
"fit": {
|
||||
"type": "string"
|
||||
},
|
||||
"mask": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"geometry": {
|
||||
"type": "string"
|
||||
},
|
||||
"adjustmentList": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "string"
|
||||
},
|
||||
"formula": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"additionalProperties": false
|
||||
}
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"geometry"
|
||||
],
|
||||
"additionalProperties": false
|
||||
},
|
||||
"prompt": {
|
||||
"type": "string"
|
||||
},
|
||||
"isPlaceholder": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"asset": {
|
||||
"$ref": "#/$defs/Asset"
|
||||
},
|
||||
"fillImage": {
|
||||
"$ref": "#/$defs/Asset"
|
||||
},
|
||||
"tableCell": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"tableId": {
|
||||
"type": "string",
|
||||
"pattern": "^(sh|im|ch|tb|ea)\\/[a-z0-9]+$"
|
||||
},
|
||||
"cellIndex": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 9007199254740991
|
||||
},
|
||||
"row": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 9007199254740991
|
||||
},
|
||||
"column": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 9007199254740991
|
||||
},
|
||||
"overlap": {
|
||||
"type": "number"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"tableId",
|
||||
"cellIndex",
|
||||
"row",
|
||||
"column",
|
||||
"overlap"
|
||||
],
|
||||
"additionalProperties": false
|
||||
},
|
||||
"cells": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/$defs/TableCell"
|
||||
}
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"id",
|
||||
"kind"
|
||||
],
|
||||
"additionalProperties": false,
|
||||
"id": "Element"
|
||||
},
|
||||
"TextStyle": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"anchor": {
|
||||
"type": "number"
|
||||
},
|
||||
"vertical": {
|
||||
"type": "number"
|
||||
},
|
||||
"rotation": {
|
||||
"type": "number"
|
||||
},
|
||||
"fontSize": {
|
||||
"type": "number"
|
||||
},
|
||||
"name": {
|
||||
"type": "string"
|
||||
},
|
||||
"family": {
|
||||
"type": "number"
|
||||
},
|
||||
"scheme": {
|
||||
"type": "string"
|
||||
},
|
||||
"typeface": {
|
||||
"type": "string"
|
||||
},
|
||||
"color": {
|
||||
"$ref": "#/$defs/Color"
|
||||
},
|
||||
"bold": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"italic": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"alignment": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"left",
|
||||
"center",
|
||||
"right",
|
||||
"justify"
|
||||
]
|
||||
},
|
||||
"verticalAlignment": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"top",
|
||||
"middle",
|
||||
"bottom"
|
||||
]
|
||||
},
|
||||
"lineSpacing": {
|
||||
"type": "number"
|
||||
},
|
||||
"textTransform": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"none",
|
||||
"uppercase",
|
||||
"smallCaps"
|
||||
]
|
||||
},
|
||||
"wrap": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"square",
|
||||
"none"
|
||||
]
|
||||
},
|
||||
"autoFit": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"none",
|
||||
"shrinkText",
|
||||
"resizeShapeToFitText"
|
||||
]
|
||||
},
|
||||
"autoFitScale": {
|
||||
"type": "number"
|
||||
},
|
||||
"autoFitLineSpaceReduction": {
|
||||
"type": "number"
|
||||
},
|
||||
"insets": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"top": {
|
||||
"type": "number"
|
||||
},
|
||||
"right": {
|
||||
"type": "number"
|
||||
},
|
||||
"bottom": {
|
||||
"type": "number"
|
||||
},
|
||||
"left": {
|
||||
"type": "number"
|
||||
}
|
||||
},
|
||||
"additionalProperties": false
|
||||
},
|
||||
"useParagraphSpacing": {
|
||||
"type": "boolean"
|
||||
}
|
||||
},
|
||||
"additionalProperties": false,
|
||||
"id": "TextStyle"
|
||||
},
|
||||
"Paragraph": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"index": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 9007199254740991
|
||||
},
|
||||
"text": {
|
||||
"type": "string"
|
||||
},
|
||||
"bulletCharacter": {
|
||||
"type": "string"
|
||||
},
|
||||
"marginLeft": {
|
||||
"type": "number"
|
||||
},
|
||||
"indent": {
|
||||
"type": "number"
|
||||
},
|
||||
"lineSpacingPercent": {
|
||||
"type": "number"
|
||||
},
|
||||
"spaceBefore": {
|
||||
"type": "number"
|
||||
},
|
||||
"spaceAfter": {
|
||||
"type": "number"
|
||||
},
|
||||
"style": {
|
||||
"$ref": "#/$defs/TextStyle"
|
||||
},
|
||||
"runs": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/$defs/TextRun"
|
||||
}
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"index",
|
||||
"runs"
|
||||
],
|
||||
"additionalProperties": false,
|
||||
"id": "Paragraph"
|
||||
},
|
||||
"TextRun": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"anchor": {
|
||||
"type": "number"
|
||||
},
|
||||
"vertical": {
|
||||
"type": "number"
|
||||
},
|
||||
"rotation": {
|
||||
"type": "number"
|
||||
},
|
||||
"fontSize": {
|
||||
"type": "number"
|
||||
},
|
||||
"name": {
|
||||
"type": "string"
|
||||
},
|
||||
"family": {
|
||||
"type": "number"
|
||||
},
|
||||
"scheme": {
|
||||
"type": "string"
|
||||
},
|
||||
"typeface": {
|
||||
"type": "string"
|
||||
},
|
||||
"color": {
|
||||
"$ref": "#/$defs/Color"
|
||||
},
|
||||
"bold": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"italic": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"alignment": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"left",
|
||||
"center",
|
||||
"right",
|
||||
"justify"
|
||||
]
|
||||
},
|
||||
"verticalAlignment": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"top",
|
||||
"middle",
|
||||
"bottom"
|
||||
]
|
||||
},
|
||||
"lineSpacing": {
|
||||
"type": "number"
|
||||
},
|
||||
"textTransform": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"none",
|
||||
"uppercase",
|
||||
"smallCaps"
|
||||
]
|
||||
},
|
||||
"wrap": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"square",
|
||||
"none"
|
||||
]
|
||||
},
|
||||
"autoFit": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"none",
|
||||
"shrinkText",
|
||||
"resizeShapeToFitText"
|
||||
]
|
||||
},
|
||||
"autoFitScale": {
|
||||
"type": "number"
|
||||
},
|
||||
"autoFitLineSpaceReduction": {
|
||||
"type": "number"
|
||||
},
|
||||
"insets": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"top": {
|
||||
"type": "number"
|
||||
},
|
||||
"right": {
|
||||
"type": "number"
|
||||
},
|
||||
"bottom": {
|
||||
"type": "number"
|
||||
},
|
||||
"left": {
|
||||
"type": "number"
|
||||
}
|
||||
},
|
||||
"additionalProperties": false
|
||||
},
|
||||
"useParagraphSpacing": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"index": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 9007199254740991
|
||||
},
|
||||
"text": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"index",
|
||||
"text"
|
||||
],
|
||||
"additionalProperties": false,
|
||||
"id": "TextRun"
|
||||
},
|
||||
"Asset": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"contentType": {
|
||||
"type": "string"
|
||||
},
|
||||
"uri": {
|
||||
"type": "string"
|
||||
},
|
||||
"prompt": {
|
||||
"type": "string"
|
||||
},
|
||||
"byteLength": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 9007199254740991
|
||||
}
|
||||
},
|
||||
"additionalProperties": false,
|
||||
"id": "Asset"
|
||||
},
|
||||
"TableCell": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"index": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 9007199254740991
|
||||
},
|
||||
"row": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 9007199254740991
|
||||
},
|
||||
"column": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 9007199254740991
|
||||
},
|
||||
"rowSpan": {
|
||||
"type": "integer",
|
||||
"exclusiveMinimum": 0,
|
||||
"maximum": 9007199254740991
|
||||
},
|
||||
"colSpan": {
|
||||
"type": "integer",
|
||||
"exclusiveMinimum": 0,
|
||||
"maximum": 9007199254740991
|
||||
},
|
||||
"position": {
|
||||
"$ref": "#/$defs/Position"
|
||||
},
|
||||
"text": {
|
||||
"type": "string"
|
||||
},
|
||||
"textDirection": {
|
||||
"type": "string"
|
||||
},
|
||||
"fillColor": {
|
||||
"$ref": "#/$defs/Color"
|
||||
},
|
||||
"style": {
|
||||
"$ref": "#/$defs/TextStyle"
|
||||
},
|
||||
"paragraphs": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/$defs/Paragraph"
|
||||
}
|
||||
},
|
||||
"ownedElementIds": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string",
|
||||
"pattern": "^(sh|im|ch|tb|ea)\\/[a-z0-9]+$"
|
||||
}
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"index",
|
||||
"row",
|
||||
"column"
|
||||
],
|
||||
"additionalProperties": false,
|
||||
"id": "TableCell"
|
||||
},
|
||||
"Notes": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"pattern": "^nt\\/[a-z0-9]+$"
|
||||
},
|
||||
"kind": {
|
||||
"type": "string",
|
||||
"const": "notes"
|
||||
},
|
||||
"text": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"id",
|
||||
"kind",
|
||||
"text"
|
||||
],
|
||||
"additionalProperties": false,
|
||||
"id": "Notes"
|
||||
},
|
||||
"InheritedLayer": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"pattern": "^ly\\/[a-z0-9]+$"
|
||||
},
|
||||
"scope": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"layout",
|
||||
"master"
|
||||
]
|
||||
},
|
||||
"name": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": {
|
||||
"type": "string"
|
||||
},
|
||||
"parentLayoutId": {
|
||||
"type": "string",
|
||||
"pattern": "^ly\\/[a-z0-9]+$"
|
||||
},
|
||||
"backgroundColor": {
|
||||
"$ref": "#/$defs/Color"
|
||||
},
|
||||
"backgroundImage": {
|
||||
"$ref": "#/$defs/Asset"
|
||||
},
|
||||
"elements": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/$defs/Element"
|
||||
}
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"id",
|
||||
"scope",
|
||||
"elements"
|
||||
],
|
||||
"additionalProperties": false,
|
||||
"id": "InheritedLayer"
|
||||
}
|
||||
}
|
||||
}
|
||||
Generated
Vendored
+227
@@ -0,0 +1,227 @@
|
||||
# Presentation JSX Reference
|
||||
|
||||
This is the compact API reference for authoring editable presentations with
|
||||
presentation JSX. It describes the node vocabulary and layout mechanics. For
|
||||
first-principles row, column, grid, alignment, mask, and overlay recipes, read
|
||||
`cookbook/layout.md`.
|
||||
|
||||
Examples start after `presentation` and `slide` exist.
|
||||
|
||||
## Authoring Defaults
|
||||
|
||||
- Use JSX for structured slide layout: `slide.compose(<row ... />, { frame })`.
|
||||
- Use string sizing where supported: `width="fill"`, `height="hug"`,
|
||||
`height="fill"`.
|
||||
- Use raw pixel numbers for fixed sizes: `width={420}`, `gap={24}`,
|
||||
`padding={{ x: 48, y: 40 }}`.
|
||||
- Use Tailwind-like tokens for common styling: `fill="slate-950"`,
|
||||
`borderRadius="rounded-xl"`, `shadow="shadow-md"`,
|
||||
`className="bg-white rounded-xl shadow-sm"`.
|
||||
- Use `row`, `column`, `grid`, `layers`, and `box` for layout. Use absolute
|
||||
slide frames only for the outer composed region, fixed chrome, and
|
||||
imported-template details. For overlays, scrims, and masked image
|
||||
compositions inside a region, use `layers` and image `geometry`/`borderRadius`.
|
||||
- Put text in `paragraph` and inline emphasis in child `run` nodes.
|
||||
- Put real data in native `table` and `chart` nodes.
|
||||
- Model-facing examples use string sizing and local track objects instead of
|
||||
imported sizing helpers such as `wrap(...)`, `grow(...)`, and `fr(...)`.
|
||||
|
||||
## JSX Usage Rules
|
||||
|
||||
Use JSX props for layout and token strings for common visual styling:
|
||||
|
||||
| Need | Use |
|
||||
| --- | --- |
|
||||
| Layout sizing | `width="fill"`, `height={320}`, `gap={24}`, `padding={{ x: 32, y: 24 }}` |
|
||||
| Flex flow | `<row align="center" justify="between">` and `<column gap={16}>` |
|
||||
| Grid tracks | local arrays such as `[{ mode: "fr", value: 1 }]` |
|
||||
| Visual tokens | `className="bg-white rounded-xl shadow-sm"` |
|
||||
| Exact text | `style="font: 700 28px Inter; color: #0f172a; leading: 1.1"` |
|
||||
| Gradients | `fill="linear(135deg, #fff 0%, sky-100 100%)"` |
|
||||
| Image masks | `<image geometry="ellipse" crop={...} fit="cover" />` |
|
||||
|
||||
## Canonical Node Set
|
||||
|
||||
### Slide Roots
|
||||
|
||||
| Node | Purpose | Common props |
|
||||
| --- | --- | --- |
|
||||
| `slide` | Whole-slide JSX root | `id`, `name`, `width`, `height`, `padding`, `gap`, `align`, `justify`, `background`, `backgroundRef` |
|
||||
| `background` | Slide background metadata | `fill`, `ref` |
|
||||
|
||||
Most code composes directly into an existing `slide` facade rather than using a
|
||||
`<slide>` root.
|
||||
|
||||
### Layout Nodes
|
||||
|
||||
| Node | Purpose | Common props |
|
||||
| --- | --- | --- |
|
||||
| `row` | Horizontal flex-like layout | `width`, `height`, `gap`, `align`, `justify`, `padding` |
|
||||
| `column` | Vertical flex-like layout | `width`, `height`, `gap`, `align`, `justify`, `padding` |
|
||||
| `grid` | Track layout with spans | `columns`, `rows`, `autoRows`, `columnGap`, `rowGap`, `alignItems`, `justifyItems`, `padding` |
|
||||
| `layers` | Overlay children in one frame | `width`, `height`, `padding`, `alignItems`, `justifyItems` |
|
||||
| `box` | Surface/container with one child region | `width`, `height`, `padding`, `align`, `justify`, `fill`, `line`, `borderRadius`, `shadow`, `className` |
|
||||
|
||||
`align` controls the cross axis. `justify` controls the main axis. Supported
|
||||
values are `"start"`, `"center"`, `"end"`, `"stretch"` for alignment and
|
||||
`"start"`, `"center"`, `"end"`, `"between"` for distribution.
|
||||
|
||||
All direct grid children support `columnSpan` and `rowSpan`, including
|
||||
`row`, `column`, `box`, `paragraph`, `shape`, `image`, `table`, and `chart`.
|
||||
|
||||
### Content Nodes
|
||||
|
||||
| Node | Purpose | Common props |
|
||||
| --- | --- | --- |
|
||||
| `paragraph` | Text block | `width`, `height`, `style`, `className`, `transform`, `bulletCharacter`, `marginLeft`, `indent`, `spaceBefore`, `spaceAfter`, `styleId`, `paragraphStyle` |
|
||||
| `run` | Inline text run | children, `textStyle`, `className`, `link` |
|
||||
| `shape` | Primitive drawing | `geometry`, `width`, `height`, `fill`, `line`, `borderRadius`, `shadow`, `className` |
|
||||
| `image` | Raster/vector image | `path`, `blob`, `dataUrl`, `svg`, `prompt`, `contentType`, `fit`, `alt`, `geometry`, `borderRadius`, `crop`, `rotation`, `flipHorizontal`, `flipVertical`, `lockAspectRatio`, `width`, `height` |
|
||||
| `rule` | Divider line | `stroke`, `weight`, `opacity`, `width`, `height` |
|
||||
| `table` | Native table | `rows`, `columns`, `values`, `style`, `styleOptions`, `width`, `height` |
|
||||
| `chart` | Native chart | `chartType`, `title`, `categories`, `series`, `legend`, `xAxis`, `yAxis`, `width`, `height` |
|
||||
|
||||
`id` and `name` are supported on materialized nodes. Use deterministic
|
||||
kebab-case `name` values on composed roots and important descendants:
|
||||
`content-frame`, `primary-heading`, `metrics-grid`, `chart-frame`, `revenue-chart`.
|
||||
Names should describe role, not visual position. Use `id` when the calling code
|
||||
controls stability across edits.
|
||||
|
||||
### Chart Child Nodes
|
||||
|
||||
Use a compact chart config when it is clearest. Use nested chart nodes when the
|
||||
JSX tree should expose structure.
|
||||
|
||||
| Node | Purpose |
|
||||
| --- | --- |
|
||||
| `bar`, `line`, `area`, `scatter`, `bubble`, `radar`, `pie`, `doughnut`, `treemap`, `sunburst`, `map`, `waterfall`, `funnel`, `histogram`, `boxWhisker`, `stock`, `surface`, `surface3D`, `pareto`, `combo`, `line3D`, `pie3D`, `area3D`, `bar3D`, `ofPie` | Chart family selector/options |
|
||||
| `legend`, `data-labels`, `data-table`, `x-axis`, `y-axis`, `axis`, `major-gridlines`, `minor-gridlines` | Chart chrome and axes |
|
||||
| `series`, `marker`, `point`, `data-label`, `trendline`, `trendline-label`, `error-bars` | Series and point-level options |
|
||||
| `view-3d` | 3D camera options |
|
||||
|
||||
## Sizing And Frames
|
||||
|
||||
Use these forms first:
|
||||
|
||||
| Intent | JSX |
|
||||
| --- | --- |
|
||||
| Fill parent | `width="fill"` or `height="fill"` |
|
||||
| Fit content | `width="hug"` or `height="hug"` |
|
||||
| Fixed pixels | `width={320}` or `height={180}` |
|
||||
| Equal children in a row/column | give each child `width="fill"` or `height="fill"` |
|
||||
| One fixed region plus remaining space | one child `width={520}`, sibling `width="fill"` |
|
||||
| Fixed slide region | `slide.compose(node, { frame: { left, top, width, height } })` |
|
||||
|
||||
`frame` uses numeric pixels. JSX size props accept strings for `"fill"` and
|
||||
`"hug"` plus raw pixel numbers.
|
||||
|
||||
Use `1280 x 720` as the default canvas unless the task or source deck requires
|
||||
another size. A common content frame is:
|
||||
|
||||
```ts
|
||||
const PAGE = { left: 72, top: 64, width: 1136, height: 592 };
|
||||
```
|
||||
|
||||
## Alignment Matrix
|
||||
|
||||
| Node | Main axis | Cross axis | Distribution prop | Cross-axis prop | Defaults |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| `row` | horizontal | vertical | `justify`: `start`, `center`, `end`, `between` | `align`: `start`, `center`, `end`, `stretch` | `justify="start"`, `align="start"` |
|
||||
| `column` | vertical | horizontal | `justify`: `start`, `center`, `end`, `between` | `align`: `start`, `center`, `end`, `stretch` | `justify="start"`, `align="start"` |
|
||||
| `grid` | tracks | cells | `justifyItems`: `start`, `center`, `end`, `stretch` | `alignItems`: `start`, `center`, `end`, `stretch` | both `stretch` |
|
||||
| `layers` | shared frame | shared frame | `justifyItems`: `start`, `center`, `end`, `stretch` | `alignItems`: `start`, `center`, `end`, `stretch` | both `stretch` |
|
||||
|
||||
## Layout Recipes
|
||||
|
||||
This top-level reference stays close to the JSX API. For copy-paste row,
|
||||
column, 3-column, 12-grid, alignment, mask, overlay, and gradient recipes, use
|
||||
[`cookbook/layout.md`](./cookbook/layout.md).
|
||||
|
||||
## Text Examples
|
||||
|
||||
```tsx
|
||||
<paragraph className="text-slate-950 text-4xl font-bold leading-tight">
|
||||
A paragraph can contain plain text.
|
||||
</paragraph>
|
||||
|
||||
<paragraph className="text-slate-600 text-lg leading-relaxed">
|
||||
Use <run textStyle={{ bold: true, color: "sky-600" }}>runs</run> for inline
|
||||
emphasis or links.
|
||||
</paragraph>
|
||||
|
||||
<column width="fill" height="hug" gap={8}>
|
||||
<paragraph
|
||||
width="fill"
|
||||
className="text-slate-700 text-lg leading-relaxed"
|
||||
>
|
||||
First paragraph.
|
||||
</paragraph>
|
||||
<paragraph bulletCharacter="•" marginLeft={18} indent={-10}>
|
||||
Bulleted paragraph with native list metadata.
|
||||
</paragraph>
|
||||
</column>
|
||||
```
|
||||
|
||||
Use `style={{ ... }}` for exact text config and `className` for tokenized
|
||||
common text styling. A string `style` containing `:` or `;` is parsed as a
|
||||
compact text declaration; any other string is treated as a named presentation
|
||||
style id.
|
||||
|
||||
```tsx
|
||||
<paragraph style="font: 700 22px Inter; color: #334155; leading: 1.25; wrap: none">
|
||||
Exact style string
|
||||
</paragraph>
|
||||
```
|
||||
|
||||
## Tables And Charts
|
||||
|
||||
Prefer compact config for data objects.
|
||||
|
||||
```tsx
|
||||
<table
|
||||
rows={3}
|
||||
columns={3}
|
||||
values={[
|
||||
["Metric", "Q1", "Q2"],
|
||||
["Revenue", 12, 18],
|
||||
["Margin", "42%", "45%"],
|
||||
]}
|
||||
style="TableStyleMedium2"
|
||||
styleOptions={{ headerRow: true, bandedRows: true }}
|
||||
width="fill"
|
||||
height={220}
|
||||
/>
|
||||
|
||||
<chart
|
||||
chartType="bar"
|
||||
title="Pipeline"
|
||||
categories={["Q1", "Q2", "Q3"]}
|
||||
series={[{ name: "Revenue", values: [12, 18, 24], fill: "sky-500" }]}
|
||||
xAxis={{ textStyle: { fontSize: 10, fill: "slate-600" } }}
|
||||
yAxis={{ majorGridlines: { style: "solid", fill: "slate-200", width: 1 } }}
|
||||
width="fill"
|
||||
height={280}
|
||||
/>
|
||||
```
|
||||
|
||||
Use nested chart nodes when the chart needs explicit series, point, trendline,
|
||||
axis, or label structure in the JSX tree.
|
||||
|
||||
## Image Sources
|
||||
|
||||
| Source prop | Use when |
|
||||
| --- | --- |
|
||||
| `blob={bytes}` | Export must embed the actual image bytes. |
|
||||
| `dataUrl="data:image/..."` | Bytes are already encoded inline. |
|
||||
| `path="/assets/image.png"` | A downloaded image is available as a local file. |
|
||||
| `prompt="..."` | The slide should contain an image-generation placeholder. |
|
||||
|
||||
Use `fit="contain"` when the full image must remain visible. Use `fit="cover"`
|
||||
when cropping is deliberate. Keep labels and data as editable slide text layered
|
||||
with the image.
|
||||
|
||||
## Reference Tests
|
||||
|
||||
- `tests/presentation/jsx.spec.tsx`: JSX normalization and compose behavior.
|
||||
- `tests/presentation/jsx-style-language.spec.tsx`: compact style strings.
|
||||
- `tests/presentation/tailwind-tokens.sanity.spec.ts`: token coverage.
|
||||
Generated
Vendored
+155
@@ -0,0 +1,155 @@
|
||||
# Layouts
|
||||
|
||||
Layouts define reusable placeholder structure for slides.
|
||||
|
||||
## Create A Layout
|
||||
|
||||
```ts
|
||||
const layout = presentation.layouts.add(layoutName);
|
||||
layout.placeholders.add({
|
||||
type: placeholderType,
|
||||
index: placeholderIndex,
|
||||
text: placeholderText,
|
||||
geometry: "textbox",
|
||||
});
|
||||
```
|
||||
|
||||
## Placeholder Inline Type
|
||||
|
||||
```ts
|
||||
type PlaceholderConfig = {
|
||||
type?:
|
||||
| "title"
|
||||
| "subtitle"
|
||||
| "body"
|
||||
| "picture"
|
||||
| "chart"
|
||||
| "table"
|
||||
| "content";
|
||||
index?: number;
|
||||
text?: TextValue;
|
||||
geometry?: "textbox" | "rect" | "roundRect" | string;
|
||||
position?: { left?: number; top?: number; width?: number; height?: number };
|
||||
fill?: FillConfig;
|
||||
line?: LineConfig;
|
||||
};
|
||||
```
|
||||
|
||||
## Shape-Based Placeholders
|
||||
|
||||
```ts
|
||||
const placeholder = layout.shapes.addPlaceholder(placeholderName);
|
||||
placeholder.placeholder.type = placeholderType;
|
||||
placeholder.placeholder.index = placeholderIndex;
|
||||
placeholder.text = placeholderText;
|
||||
```
|
||||
|
||||
## Use A Layout
|
||||
|
||||
```ts
|
||||
slide.setLayout(layout);
|
||||
|
||||
const target = slide.placeholders.getItem(placeholderType);
|
||||
target.text = textValue;
|
||||
```
|
||||
|
||||
## Discover
|
||||
|
||||
```ts
|
||||
const layoutSummary = layout.placeholders.summary();
|
||||
const resolved = presentation.layouts.getById(layout.id);
|
||||
const importedGuides = layout.slideGuides;
|
||||
const actualPlaceholders = slide.placeholders.items;
|
||||
const emptyContentPlaceholders = slide.placeholders.editable;
|
||||
const allVisibleEmptyPlaceholders = slide.placeholders.unfilled;
|
||||
const missingLayoutSlots = slide.placeholders.availableFromLayout;
|
||||
```
|
||||
|
||||
These getters do not modify saved slide content.
|
||||
`items` includes filled placeholders. `editable` contains visible empty content
|
||||
shapes with positive bounds; `unfilled` also includes empty furniture.
|
||||
`availableFromLayout` contains missing layout slots for explicit creation.
|
||||
`getAll()` retains layout/master discovery, and `getItem()` creates a local
|
||||
instance when the requested placeholder exists only in the layout or master.
|
||||
|
||||
## Preview And Insert A Layout
|
||||
|
||||
```ts
|
||||
presentation.view.showPlaceholders();
|
||||
const image = await layout.export({ format: "png", scale: 0.25 });
|
||||
|
||||
const { slide } = presentation.slides.insert({
|
||||
after: selectedSlide,
|
||||
layoutId: layout.id,
|
||||
});
|
||||
slide.placeholders.addFromLayout();
|
||||
slide.placeholders.getItem("title").text = titleText;
|
||||
```
|
||||
|
||||
`addFromLayout()` creates missing content placeholders once and returns the
|
||||
created shapes. Adding a slide alone leaves placeholder creation to the caller.
|
||||
|
||||
## Cookbook
|
||||
|
||||
```ts
|
||||
// Branded title/body layout.
|
||||
const layout = presentation.layouts.add("Title Body");
|
||||
layout.placeholders.add({
|
||||
type: "title",
|
||||
index: 0,
|
||||
geometry: "textbox",
|
||||
position: { left: 72, top: 64, width: 920, height: 88 },
|
||||
text: "Title",
|
||||
});
|
||||
layout.placeholders.add({
|
||||
type: "body",
|
||||
index: 0,
|
||||
geometry: "roundRect",
|
||||
position: { left: 72, top: 180, width: 760, height: 360 },
|
||||
fill: "slate-50",
|
||||
line: { style: "solid", fill: "slate-200", width: 1 },
|
||||
});
|
||||
```
|
||||
|
||||
```ts
|
||||
// Use placeholders for repeated structure; override slide content locally.
|
||||
const slide = presentation.slides.add({ layout: "Title Body" });
|
||||
slide.placeholders.getItem("title").text = "Market overview";
|
||||
slide.placeholders.getItem("body").text = "Three editable points go here.";
|
||||
```
|
||||
|
||||
## Read A Rendered Slide's Layout
|
||||
|
||||
Each `presentation.render()` preview is an image Blob with a `.layout` JSON Blob.
|
||||
The paired files use the same stem, for example `slide-1.png` and
|
||||
`slide-1.layout.json`. A complete render replaces the previous render set;
|
||||
a subset render updates only the selected slides' pairs.
|
||||
|
||||
```ts
|
||||
const preview = await presentation.render({ slide: 0 });
|
||||
const layout = JSON.parse(await preview.layout.text());
|
||||
const title = layout.elements.find((element) => element.name === "cover-title");
|
||||
if (title) presentation.resolve(title.id).text = "Updated title";
|
||||
```
|
||||
|
||||
The default `openai.presentation.layout/v5` view is compact and uses pixels and
|
||||
canonical IDs. Request `slide.export({ format: "layout", detail: "full" })` for
|
||||
inherited paint layers, paragraph/run formatting, and table-cell details.
|
||||
Both views use the same IDs and editing coordinates:
|
||||
|
||||
| Field | Meaning |
|
||||
| ---------------------------------------------- | ------------------------------------------------------------------------------------------ |
|
||||
| `slide.id`, `slide.index` | Canonical slide ID and zero-based deck index. |
|
||||
| `slide.position` | Slide bounds: `{ left, top, width, height }`. |
|
||||
| `elements[].id`, `kind`, `name` | Canonical element ID, element kind, and optional authored name. |
|
||||
| `elements[].position` | Bounds using the same keys as edit configuration. |
|
||||
| `elements[].text`, `style` | Text and effective text styling, including `style.fontSize`. |
|
||||
| `elements[].crop`, `fit`, `mask` | Image crop, fitting, and geometry configuration. |
|
||||
| `elements[].scope`, `editable` | Owned slide content is editable; inherited layout/master content is identified separately. |
|
||||
| `tableCell.tableId`, `cells[].ownedElementIds` | Canonical IDs connecting a table, its cells, and cell-owned elements. |
|
||||
| `inheritedLayers[].id` | Canonical `ly/…` ID of a layout or master. |
|
||||
|
||||
Pass IDs from editable records to `presentation.resolve()` or
|
||||
`presentation.delete()`. In the full view, inherited content has `editable: false`; its IDs identify
|
||||
where the content came from and are not slide-owned edit targets. Raw PowerPoint
|
||||
IDs, asset IDs, and paragraph style IDs are not part of this public view.
|
||||
Generated
Vendored
+57
@@ -0,0 +1,57 @@
|
||||
# Masters
|
||||
|
||||
Masters share theme, background, and color-map structure with child layouts.
|
||||
|
||||
## Create And Link
|
||||
|
||||
```ts
|
||||
const master = presentation.masters.add(masterName);
|
||||
const layout = presentation.layouts.add(layoutName);
|
||||
|
||||
layout.setParentLayoutId(master.id);
|
||||
```
|
||||
|
||||
## Color Map And Background
|
||||
|
||||
```ts
|
||||
master.setColorMap(colorMapConfig);
|
||||
master.background.ref = backgroundRef;
|
||||
|
||||
const slide = presentation.slides.add();
|
||||
slide.setLayout(layout);
|
||||
```
|
||||
|
||||
## Master Inline Types
|
||||
|
||||
```ts
|
||||
type ColorMapConfig = Partial<Record<
|
||||
"bg1" | "tx1" | "bg2" | "tx2" | "accent1" | "accent2" | "accent3" | "accent4" | "accent5" | "accent6" | "hlink" | "folHlink",
|
||||
"bg1" | "tx1" | "bg2" | "tx2" | "accent1" | "accent2" | "accent3" | "accent4" | "accent5" | "accent6" | "hlink" | "folHlink"
|
||||
>>;
|
||||
```
|
||||
|
||||
## Resolve
|
||||
|
||||
```ts
|
||||
const resolved = presentation.layouts.getById(master.id);
|
||||
```
|
||||
|
||||
## Cookbook
|
||||
|
||||
```ts
|
||||
// Shared brand master with inherited layout.
|
||||
const master = presentation.masters.add("Brand Master");
|
||||
master.setColorMap({ bg1: "bg1", tx1: "tx1", accent1: "accent1" });
|
||||
master.background.ref = "bg1";
|
||||
|
||||
const layout = presentation.layouts.add("Brand Title");
|
||||
layout.setParentLayoutId(master.id);
|
||||
layout.placeholders.add({
|
||||
type: "title",
|
||||
geometry: "textbox",
|
||||
position: { left: 72, top: 72, width: 1000, height: 96 },
|
||||
});
|
||||
```
|
||||
|
||||
Before editing a master in an imported deck, inspect affected layouts and
|
||||
slides; master edits have intentional global blast radius.
|
||||
Generated
Vendored
+291
@@ -0,0 +1,291 @@
|
||||
# Presentation Facade
|
||||
|
||||
## Create And Load
|
||||
|
||||
```ts
|
||||
const presentation = Presentation.create({ slideSize });
|
||||
const loaded = await Presentation.load("input.pptx");
|
||||
const imported = Presentation.load(proto);
|
||||
```
|
||||
|
||||
## Create Inline Type
|
||||
|
||||
```ts
|
||||
type PresentationCreateOptions = {
|
||||
slideSize?: { width: number; height: number };
|
||||
};
|
||||
```
|
||||
|
||||
## Presentation Slide Collection
|
||||
|
||||
```ts
|
||||
const slide = presentation.slides.add({ layout, layoutId, background: { fill } });
|
||||
const inserted = presentation.slides.insert({ after, layout, layoutId });
|
||||
const byIndex = presentation.slides.getItem(slideIndex);
|
||||
presentation.slides.keep([0, 2, 4]);
|
||||
presentation.slides.reorder(orderedSlideIds);
|
||||
```
|
||||
|
||||
`keep` accepts an array of zero-based indexes or an array of canonical `sl/` IDs.
|
||||
It validates the selection against the current slide list, then preserves the
|
||||
selected slides in their existing relative order. Repeated selections are ignored;
|
||||
an empty array deletes all slides. `reorder` requires the complete desired order,
|
||||
with every current slide ID exactly once. Invalid selections fail before mutation.
|
||||
|
||||
## Presentation Slide Collection Inline Types
|
||||
|
||||
```ts
|
||||
type SlideAddOptions = {
|
||||
layout?: string;
|
||||
layoutId?: string;
|
||||
width?: number;
|
||||
height?: number;
|
||||
background?: { fill: FillConfig };
|
||||
};
|
||||
|
||||
type SlideInsertOptions = SlideAddOptions & {
|
||||
after?: Slide | number | null;
|
||||
};
|
||||
|
||||
interface SlideCollection {
|
||||
keep(selection: readonly number[] | readonly string[]): void;
|
||||
reorder(ids: readonly string[]): void;
|
||||
}
|
||||
|
||||
interface Presentation {
|
||||
delete(ids: string | readonly string[]): void;
|
||||
}
|
||||
```
|
||||
|
||||
## Discover And Edit
|
||||
|
||||
```ts
|
||||
const snapshot = await presentation.inspect({
|
||||
kind,
|
||||
search,
|
||||
limit,
|
||||
offset,
|
||||
});
|
||||
|
||||
const target = presentation.resolve(anchorId);
|
||||
const targets = presentation.resolve(anchorIds);
|
||||
presentation.delete(anchorIds);
|
||||
```
|
||||
|
||||
`delete` accepts one canonical ID or an array. It supports slides (`sl/`) and owned
|
||||
shapes, images, charts, tables, and embedded artifacts (`sh/`, `im/`, `ch/`, `tb/`,
|
||||
`ea/`). All IDs are validated first. Repeated IDs are ignored; selecting a slide
|
||||
and its children deletes the slide once. Inherited elements, notes, text ranges,
|
||||
and the presentation itself are not delete targets.
|
||||
|
||||
`inspect` returns stable anchor ids for slides, shapes, images, tables, charts, text ranges, speaker notes, and comment threads. `resolve` maps one anchor id to its facade, or an array of ids to facades in the same order. Layout records expose canonical `ly/...` IDs with `editable: false` for search and comparison; pass only `pr/`, `sl/`, `sh/`, `im/`, `tb/`, `ch/`, `nt/`, `th/`, and `tr/` anchors to `resolve`.
|
||||
|
||||
## Inspect
|
||||
|
||||
Use `presentation.inspect({ select, include, fileName })` with JSONPath over the
|
||||
public presentation tree. `include` is an exact array of typed fields, including
|
||||
nested paths such as `elements.text`. The query writes all selected records to
|
||||
NDJSON in the session output directory; ordinary printing shows the count and
|
||||
file metadata. See [Inspect](./inspect.md) and the
|
||||
[inspection JSON Schema](./inspect.schema.json) for content and layout queries.
|
||||
|
||||
## Help
|
||||
|
||||
```ts
|
||||
const help = presentation.help(query, {
|
||||
search,
|
||||
include,
|
||||
maxChars,
|
||||
});
|
||||
```
|
||||
|
||||
## Help Inline Type
|
||||
|
||||
```ts
|
||||
type PresentationHelpOptions = {
|
||||
search?: string;
|
||||
include?: string[]; // common: ["index", "examples", "notes"]
|
||||
maxChars?: number;
|
||||
};
|
||||
```
|
||||
|
||||
## Presentation View
|
||||
|
||||
```ts
|
||||
presentation.view.showGridlines();
|
||||
presentation.view.showGuides();
|
||||
presentation.view.showPlaceholders();
|
||||
|
||||
const gridlinesVisible = presentation.view.gridlinesVisible;
|
||||
const guidesVisible = presentation.view.guidesVisible;
|
||||
const placeholdersVisible = presentation.view.placeholdersVisible;
|
||||
const horizontalGridSpacingEmu = presentation.view.gridSpacingCxEmu;
|
||||
const verticalGridSpacingEmu = presentation.view.gridSpacingCyEmu;
|
||||
|
||||
presentation.view.hideGridlines();
|
||||
presentation.view.hideGuides();
|
||||
presentation.view.hidePlaceholders();
|
||||
|
||||
const nextGridlineState = presentation.view.toggleGridlines();
|
||||
const nextGuideState = presentation.view.toggleGuides();
|
||||
const nextPlaceholderState = presentation.view.togglePlaceholders();
|
||||
```
|
||||
|
||||
## Render And Export
|
||||
|
||||
```ts
|
||||
const overview = await presentation.render({ montage: true, fileName: "overview.png" });
|
||||
const selectedPreviews = await presentation.render({ slide: [0, 2] }); // PNG/layout pairs
|
||||
const allPreviews = await presentation.render(); // pairs in deck order
|
||||
const firstPreview = await presentation.render({ slide: 0 }); // one image Blob with .layout
|
||||
const pptxBlob = await presentation.export({ format: "pptx", fileName: "presentation.pptx" });
|
||||
const deckPdfBlob = await presentation.export({ format: "pdf" });
|
||||
const slidePdfBlob = await presentation.export({ slide, format: "pdf" });
|
||||
const layoutBlob = await slide.export({ format: "layout" });
|
||||
const proto = presentation.toProto();
|
||||
```
|
||||
|
||||
### Montage overview
|
||||
|
||||
`render({ montage: true })` includes every slide in deck order, regardless of
|
||||
which slide is active. It returns one image Blob without per-slide layout files.
|
||||
The default format is PNG and the default filename is `presentation-montage.png`.
|
||||
A custom `fileName` names the overview. In an Artifact Session, it is published
|
||||
as one render output under the session output directory.
|
||||
|
||||
Read the montage and content inspection first, then render selected slides for
|
||||
full-size PNGs and companion layout JSON files. A montage cannot combine with
|
||||
`slide`; use a separate selected render for detailed text and layout review.
|
||||
|
||||
Pass a montage options object to configure the grid. Dimensions are pixels before
|
||||
`scale`. Defaults are 320 pixels per slide, 16 pixels of padding and gap, and
|
||||
`ceil(sqrt(slideCount))` columns. Slides retain their aspect ratios; each row uses
|
||||
its tallest slide's height. `montage.width` sets the total width and overrides
|
||||
`slideWidth`. `montage.format` overrides the outer raster format. Widths and scale
|
||||
must be positive and finite, columns must be a positive integer, and padding and
|
||||
gap must be nonnegative and finite. Montages support PNG, JPEG, and WebP.
|
||||
|
||||
### Individual slide previews
|
||||
|
||||
Without a montage, `render()` defaults to every slide. An omitted `slide` or an
|
||||
index array returns an array of image Blobs; a single index or `Slide` returns one
|
||||
image Blob. Selected arrays preserve their requested order. Default output names
|
||||
use the actual slide number, such as `slide-1.png` and `slide-3.png` for
|
||||
`slide: [0, 2]`. A custom `fileName` requires a single selected slide.
|
||||
|
||||
Each returned image Blob has a `.layout` JSON Blob containing the same slide's
|
||||
layout view. Session outputs publish both files as render outputs with matching
|
||||
stems, such as `slide-1.png` and `slide-1.layout.json`. Full-deck renders replace
|
||||
both parts of the previous render set; subset renders update only the selected
|
||||
pairs. Rendering a montage does not replace that per-slide set. See
|
||||
[the layout reference](layout.spec.md#read-a-rendered-slides-layout) for the schema.
|
||||
An empty deck or empty selection returns `[]` for individual slide rendering.
|
||||
|
||||
Use `export({ format: "pptx" })` for the editable deliverable. Existing raster
|
||||
and montage `export` options remain supported; raster `export` without a montage
|
||||
retains its single-active-slide default.
|
||||
|
||||
Use `export({ format: "pdf" })` for one PDF containing every slide in deck order,
|
||||
or pass `slide` to export one slide as PDF.
|
||||
|
||||
## Render And Export Inline Types
|
||||
|
||||
```ts
|
||||
type PresentationMontageOptions = {
|
||||
format?: "png" | "jpeg" | "webp";
|
||||
width?: number;
|
||||
slideWidth?: number;
|
||||
padding?: number;
|
||||
gap?: number;
|
||||
background?: string;
|
||||
columns?: number;
|
||||
};
|
||||
|
||||
type PresentationExportOptions = {
|
||||
fileName?: string;
|
||||
slide?: Slide;
|
||||
format?: "png" | "jpeg" | "webp" | "pdf" | "layout" | "pptx";
|
||||
width?: number;
|
||||
height?: number;
|
||||
scale?: number;
|
||||
quality?: number;
|
||||
montage?: boolean | PresentationMontageOptions;
|
||||
};
|
||||
|
||||
type PresentationRenderOptions = Omit<
|
||||
PresentationExportOptions,
|
||||
"format" | "slide"
|
||||
> & {
|
||||
format?: "png" | "jpeg" | "webp";
|
||||
slide?: Slide | number | number[];
|
||||
};
|
||||
|
||||
type PresentationRenderResult = Blob & { layout: Blob };
|
||||
|
||||
interface Presentation {
|
||||
render(options: PresentationRenderOptions & { montage: true | PresentationMontageOptions; slide?: never }): Promise<Blob>;
|
||||
render(options: PresentationRenderOptions & { montage?: false; slide: Slide | number }): Promise<PresentationRenderResult>;
|
||||
render(options?: PresentationRenderOptions & { montage?: false; slide?: number[] }): Promise<PresentationRenderResult[]>;
|
||||
}
|
||||
```
|
||||
|
||||
## Scripts
|
||||
|
||||
```ts
|
||||
const result = presentation.scripts.run(scriptKind, scriptOptions);
|
||||
```
|
||||
|
||||
Scripts provide high-level authoring recipes. Use `presentation.help(...)` to discover available script keys and option shapes.
|
||||
|
||||
## Cookbook
|
||||
|
||||
```ts
|
||||
// New deck skeleton: create, set theme, add slides, render checks.
|
||||
const presentation = Presentation.create({
|
||||
slideSize: { width: 1280, height: 720 },
|
||||
});
|
||||
presentation.theme.colorScheme = {
|
||||
name: "Clean Product",
|
||||
themeColors: {
|
||||
accent1: "#2563eb",
|
||||
accent2: "#0f766e",
|
||||
accent3: "#f59e0b",
|
||||
accent4: "#dc2626",
|
||||
accent5: "#7c3aed",
|
||||
accent6: "#16a34a",
|
||||
bg1: "#ffffff",
|
||||
bg2: "#f8fafc",
|
||||
tx1: "#0f172a",
|
||||
tx2: "#475569",
|
||||
dk1: "#000000",
|
||||
dk2: "#1e293b",
|
||||
lt1: "#ffffff",
|
||||
lt2: "#e2e8f0",
|
||||
hlink: "#2563eb",
|
||||
folHlink: "#7c3aed",
|
||||
},
|
||||
};
|
||||
|
||||
const first = presentation.slides.add();
|
||||
const second = presentation.slides.add();
|
||||
const third = presentation.slides.add();
|
||||
|
||||
await presentation.render({
|
||||
slide: first,
|
||||
scale: 1,
|
||||
});
|
||||
const snapshot = await presentation.inspect({
|
||||
kind: "deck,slide,textbox,chart,table",
|
||||
limit: 20,
|
||||
});
|
||||
```
|
||||
|
||||
```ts
|
||||
// Existing deck: inspect first, then resolve exact anchors.
|
||||
const before = await presentation.inspect({
|
||||
kind: "slide,textbox,shape,image,table,chart,notes,thread,layout",
|
||||
search: "Customer growth",
|
||||
limit: 20,
|
||||
});
|
||||
const target = presentation.resolve(anchorIdFromBefore);
|
||||
```
|
||||
Generated
Vendored
+256
@@ -0,0 +1,256 @@
|
||||
# Rich Text
|
||||
|
||||
Shape text accepts strings, paragraph arrays, and structured runs.
|
||||
|
||||
## Set Text
|
||||
|
||||
```ts
|
||||
shape.text = textValue;
|
||||
shape.text = paragraphs;
|
||||
shape.text = structuredRuns;
|
||||
```
|
||||
|
||||
## Text Value Inline Types
|
||||
|
||||
```ts
|
||||
type TextValue = string | string[] | StructuredTextInput | Text;
|
||||
|
||||
type StructuredTextInput =
|
||||
| ParagraphRunsInput
|
||||
| StructuredTextParagraphInput
|
||||
| Array<ParagraphRunsInput | StructuredTextParagraphInput>;
|
||||
|
||||
type ParagraphRunsInput = Array<string | number | TextRunInput>;
|
||||
|
||||
type StructuredTextParagraphInput = {
|
||||
runs?: ParagraphRunsInput;
|
||||
bulletCharacter?: string;
|
||||
marginLeft?: number;
|
||||
indent?: number;
|
||||
spaceBefore?: number;
|
||||
spaceAfter?: number;
|
||||
styleId?: string;
|
||||
paragraphStyle?: Record<string, unknown>;
|
||||
};
|
||||
|
||||
type TextRunInput = {
|
||||
run: string;
|
||||
style?: {
|
||||
bold?: boolean;
|
||||
italic?: boolean;
|
||||
underline?: string;
|
||||
fontSize?: string;
|
||||
typeface?: string;
|
||||
color?: FillConfig;
|
||||
};
|
||||
textStyle?: TextRunInput["style"]; // Compatibility alias.
|
||||
link?: { uri: string; isExternal: boolean; action?: string };
|
||||
};
|
||||
```
|
||||
|
||||
`style` takes precedence as a complete object when both `style` and `textStyle` are supplied.
|
||||
|
||||
Structured run `fontSize` accepts unit strings such as `"20pt"` and `"28px"`.
|
||||
Shape text style setters use numeric pixels with `fontSize` and numeric points
|
||||
with `fontSizePt`.
|
||||
|
||||
## Structured Paragraphs
|
||||
|
||||
```ts
|
||||
shape.text.set([
|
||||
[{ run: "Status", style: { bold: true } }, { run: " review" }],
|
||||
{
|
||||
bulletCharacter: "•",
|
||||
marginLeft: 18,
|
||||
indent: -10,
|
||||
runs: [
|
||||
"Open the",
|
||||
{
|
||||
run: " rollout notes",
|
||||
style: { underline: "sng", color: "#2563eb" },
|
||||
link: { uri: "https://example.com", isExternal: true },
|
||||
},
|
||||
],
|
||||
},
|
||||
]);
|
||||
```
|
||||
|
||||
The paragraph-object form is the non-JSX peer of `<paragraph>...</paragraph>`. Use it when the text needs paragraph metadata plus authored runs.
|
||||
|
||||
## JSX Rich Text
|
||||
|
||||
```tsx
|
||||
/** @jsxRuntime automatic */
|
||||
|
||||
slide.compose(
|
||||
<column width="fill" height="hug" gap={8}>
|
||||
<paragraph width="fill" className="text-slate-950 text-2xl leading-tight">
|
||||
<run textStyle={{ bold: true }}>Status</run>
|
||||
<run> review</run>
|
||||
</paragraph>
|
||||
<paragraph
|
||||
width="fill"
|
||||
className="text-slate-950 text-2xl leading-tight"
|
||||
bulletCharacter="•"
|
||||
marginLeft={18}
|
||||
indent={-10}
|
||||
>
|
||||
Open the
|
||||
<run
|
||||
textStyle={{ underline: "sng", color: "#2563eb" }}
|
||||
link={{ uri: "https://example.com", isExternal: true }}
|
||||
>
|
||||
{" rollout notes"}
|
||||
</run>
|
||||
</paragraph>
|
||||
</column>,
|
||||
{
|
||||
frame: { left: 48, top: 40, width: 864, height: 160 },
|
||||
baseUnit: 8,
|
||||
},
|
||||
);
|
||||
```
|
||||
|
||||
## Shape Text Style
|
||||
|
||||
```ts
|
||||
shape.text.style = {
|
||||
styleName,
|
||||
fontSize: fontSizePx,
|
||||
color: colorConfig,
|
||||
fill: fillConfig,
|
||||
outline: lineConfig,
|
||||
alignment,
|
||||
verticalAlignment,
|
||||
autoFit: autoFitMode,
|
||||
wrap: wrapMode,
|
||||
insets,
|
||||
};
|
||||
```
|
||||
|
||||
Use grouped `text.style = { ... }` for whole-shape text formatting. Use single
|
||||
property setters for focused edits:
|
||||
|
||||
```ts
|
||||
shape.text.fontSize = fontSizePx;
|
||||
shape.text.color = colorConfig;
|
||||
shape.text.fill = fillConfig;
|
||||
shape.text.outline = lineConfig;
|
||||
shape.text.alignment = alignment;
|
||||
shape.text.verticalAlignment = verticalAlignment;
|
||||
shape.text.autoFit = autoFitMode;
|
||||
shape.text.wrap = wrapMode;
|
||||
shape.text.insets = 0; // Set all four sides; use an object for individual sides.
|
||||
```
|
||||
|
||||
`shape.text.color` uses `ColorConfig`. `shape.text.fill`, run `style.fill`,
|
||||
and text ranges accept the shared `FillConfig`, including linear and path
|
||||
gradients. `shape.text.outline`, run `style.outline`, and text ranges accept
|
||||
`LineConfig`; the outline line fill can be a solid, pattern, or gradient fill.
|
||||
|
||||
```ts
|
||||
shape.text.fill = {
|
||||
type: "gradient",
|
||||
gradientKind: "linear",
|
||||
angleDeg: 0,
|
||||
stops: [
|
||||
{ offset: 0, color: "#ff5a5f" },
|
||||
{ offset: 100000, color: "#4f46e5" },
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
Path gradients use the same fill config with `gradientKind: "path"`, `pathType`, and optional
|
||||
`fillRect` in thousandths of a percent (`100000` = 100%).
|
||||
|
||||
## Text Style Inline Type
|
||||
|
||||
```ts
|
||||
type TextStyleConfig = {
|
||||
styleName?: string;
|
||||
className?: string;
|
||||
bold?: boolean;
|
||||
italic?: boolean;
|
||||
fontSize?: number;
|
||||
lineSpacing?: number;
|
||||
alignment?: "left" | "center" | "right" | "justify";
|
||||
verticalAlignment?: "top" | "middle" | "bottom";
|
||||
underline?: string;
|
||||
fill?: FillConfig;
|
||||
color?: ColorConfig;
|
||||
outline?: LineConfig;
|
||||
wrap?: "square" | "none";
|
||||
autoFit?: "none" | "shrinkText" | "resizeShapeToFitText";
|
||||
insets?: number | { top?: number; right?: number; bottom?: number; left?: number };
|
||||
typeface?: string;
|
||||
};
|
||||
```
|
||||
|
||||
## Ranges
|
||||
|
||||
```ts
|
||||
const range = shape.text.get(searchText);
|
||||
range.bold = isBold;
|
||||
range.italic = isItalic;
|
||||
range.fill = fillConfig;
|
||||
range.outline = lineConfig;
|
||||
range.link = linkConfig;
|
||||
|
||||
const fixedRange = shape.text.getRange(start, length);
|
||||
fixedRange.style = styleName;
|
||||
```
|
||||
|
||||
## Lists
|
||||
|
||||
```ts
|
||||
shape.text = listParagraphs;
|
||||
shape.text.style = listStyleName;
|
||||
shape.text.get(itemText).lineSpacing = lineSpacing;
|
||||
```
|
||||
|
||||
## Links
|
||||
|
||||
```ts
|
||||
shape.text.get(linkText).link = {
|
||||
uri,
|
||||
isExternal,
|
||||
};
|
||||
```
|
||||
|
||||
## Link Inline Type
|
||||
|
||||
```ts
|
||||
type LinkConfig = {
|
||||
uri: string;
|
||||
isExternal: boolean;
|
||||
action?: string;
|
||||
};
|
||||
```
|
||||
|
||||
## Cookbook
|
||||
|
||||
```ts
|
||||
// Title with emphasized suffix.
|
||||
shape.text.set([
|
||||
[
|
||||
{ run: "Revenue", style: { bold: true, color: "#0f172a" } },
|
||||
{ run: " momentum", style: { color: "#2563eb" } },
|
||||
],
|
||||
]);
|
||||
shape.text.style = { fontSize: 44, lineSpacing: 0.92 };
|
||||
```
|
||||
|
||||
```ts
|
||||
// Bullets with bold lead-ins.
|
||||
shape.text.set([
|
||||
{ bulletCharacter: "•", marginLeft: 22, indent: -12, runs: [{ run: "Quality:", style: { bold: true } }, " defect rate down 31%"] },
|
||||
{ bulletCharacter: "•", marginLeft: 22, indent: -12, runs: [{ run: "Speed:", style: { bold: true } }, " p95 latency under target"] },
|
||||
]);
|
||||
```
|
||||
|
||||
```ts
|
||||
// Edit one phrase inside imported text.
|
||||
const range = shape.text.get("legacy workflow");
|
||||
range.text = "new workflow";
|
||||
range.className = "text-emerald-700 font-bold";
|
||||
```
|
||||
Generated
Vendored
+279
@@ -0,0 +1,279 @@
|
||||
# Shapes
|
||||
|
||||
`slide.shapes` creates and edits drawable slide elements.
|
||||
|
||||
## Preset Shape
|
||||
|
||||
```ts
|
||||
const shape = slide.shapes.add({
|
||||
geometry,
|
||||
name,
|
||||
position,
|
||||
fill,
|
||||
line,
|
||||
adjustmentList,
|
||||
borderRadius,
|
||||
shadow,
|
||||
className,
|
||||
text: { text: textValue, style: { styleName: textStyleName, fontSize, bold, color } },
|
||||
});
|
||||
|
||||
shape.position = nextPosition;
|
||||
```
|
||||
|
||||
`geometry` is a string preset shape name, `"textbox"`, `"connector"`, or `"custom"`.
|
||||
Set `shape.text.insets = 0` to remove all text margins. A number sets every side;
|
||||
an object sets individual sides. Creation styles also accept `insets: 0`.
|
||||
|
||||
## Resolved From Inspect
|
||||
|
||||
```ts
|
||||
const shape = presentation.resolve("sh/a1b2c3d4");
|
||||
shape.text = "Updated copy";
|
||||
shape.fill = "accent1+18/90";
|
||||
shape.line = { style: "solid", fill: "slate-200", width: 1 };
|
||||
shape.geometry = "roundRect";
|
||||
shape.geometry; // "roundRect"
|
||||
shape.borderRadius = "rounded-2xl";
|
||||
shape.shadow = "shadow-sm";
|
||||
```
|
||||
|
||||
Use `presentation.inspect({ kind: "shape,textbox", search })` to find the
|
||||
`sh/...` anchor id. Keep the resolved facade type-aware; do not rebuild an
|
||||
imported shape unless the task requires a new object.
|
||||
|
||||
## Preset Shape Inline Type
|
||||
|
||||
```ts
|
||||
type ShapePresetName = string; // common: "textbox", "rect", "roundRect", "ellipse", "line", "rightArrow"
|
||||
// Full preset list: rg "SHAPE_GEOMETRY_NAME_TO_PROTO" src/models/presentation src/assets
|
||||
|
||||
type PositionConfig = {
|
||||
left?: number;
|
||||
top?: number;
|
||||
width?: number;
|
||||
height?: number;
|
||||
rotation?: number;
|
||||
horizontalFlip?: boolean;
|
||||
verticalFlip?: boolean;
|
||||
};
|
||||
|
||||
type PresetShapeConfig = {
|
||||
geometry: ShapePresetName;
|
||||
name?: string;
|
||||
position?: PositionConfig;
|
||||
fill?: FillConfig;
|
||||
line?: LineConfig;
|
||||
adjustmentList?: Array<{ name: string; formula: string }>;
|
||||
borderRadius?: number | string; // number = pixels; string = supported rounded-* token
|
||||
shadow?: string; // shadow token, "shadow-none", or custom "2px 7px 19px #000000/17"
|
||||
className?: string;
|
||||
text?: TextValue | { text: TextValue; style?: string | ShapeTextStyleConfig };
|
||||
placeholderType?: "title" | "subtitle" | "body" | "picture" | "chart" | "table" | "content";
|
||||
placeholderIndex?: number;
|
||||
};
|
||||
```
|
||||
|
||||
## Rounded Corners
|
||||
|
||||
Prefer `borderRadius` for rect-like rounded corners:
|
||||
|
||||
```ts
|
||||
slide.shapes.add({
|
||||
geometry: "rect",
|
||||
position: { left: 80, top: 120, width: 320, height: 160 },
|
||||
fill: "white",
|
||||
borderRadius: "rounded-2xl",
|
||||
});
|
||||
|
||||
shape.borderRadius = 24;
|
||||
```
|
||||
|
||||
Numbers are pixels. Strings use supported `rounded-*` tokens. `borderRadius`
|
||||
requires a shape with width/height and is supported for `rect`, `textbox`, and
|
||||
`roundRect`-like shapes. Use `adjustmentList` only when you need exact OpenXML
|
||||
preset adjustment formulas.
|
||||
|
||||
## Rounded Rect Adjustment
|
||||
|
||||
```ts
|
||||
const rounded = slide.shapes.add({
|
||||
geometry: "roundRect",
|
||||
position,
|
||||
fill,
|
||||
line,
|
||||
adjustmentList: [{ name: "adj", formula: adjustmentFormula }],
|
||||
});
|
||||
|
||||
rounded.adjustmentList = [{ name: "adj", formula: nextAdjustmentFormula }];
|
||||
rounded.adjustmentList;
|
||||
```
|
||||
|
||||
The `adj` value uses the OpenXML shape adjustment scale for the corner radius.
|
||||
|
||||
## Custom Path
|
||||
|
||||
```ts
|
||||
const custom = slide.shapes.add({
|
||||
geometry: "custom",
|
||||
position,
|
||||
fill,
|
||||
line,
|
||||
customPaths: [
|
||||
{
|
||||
width,
|
||||
height,
|
||||
commands,
|
||||
},
|
||||
],
|
||||
});
|
||||
|
||||
custom.customPaths = nextCustomPaths;
|
||||
custom.customPaths;
|
||||
```
|
||||
|
||||
Custom path coordinates use pixels in the path viewport.
|
||||
|
||||
## Bézier Curve
|
||||
|
||||
```ts
|
||||
const curve = slide.shapes.add({
|
||||
geometry: "custom",
|
||||
name: "Bezier curve",
|
||||
position: { left: 120, top: 190, width: 720, height: 240 },
|
||||
fill: "none",
|
||||
line: { style: "solid", fill: "#2463EB", width: 3 },
|
||||
customPaths: [{
|
||||
width: 720,
|
||||
height: 240,
|
||||
commands: [
|
||||
{ moveTo: { x: 0, y: 150 } },
|
||||
{ cubicBezTo: { x1: 100, y1: 150, x2: 120, y2: 0, x: 240, y: 40 } },
|
||||
{ cubicBezTo: { x1: 360, y1: 80, x2: 320, y2: 240, x: 480, y: 190 } },
|
||||
{ cubicBezTo: { x1: 620, y1: 130, x2: 620, y2: 80, x: 720, y: 100 } },
|
||||
],
|
||||
}],
|
||||
});
|
||||
```
|
||||
|
||||
Each cubic starts at the previous endpoint; `(x1, y1)` and `(x2, y2)` are its
|
||||
control points, and `(x, y)` is its endpoint. Omit `close` for an open curve.
|
||||
These coordinates define the curve directly; `adjustmentList` is for named
|
||||
geometry parameters. Use `slide.shapes.connect(..., { kind: "curved" })` for
|
||||
a connector that follows attached shapes.
|
||||
|
||||
## Custom Path Inline Type
|
||||
|
||||
```ts
|
||||
type CustomShapeConfig = Omit<PresetShapeConfig, "geometry"> & {
|
||||
geometry: "custom";
|
||||
customPaths: Array<{
|
||||
id?: string;
|
||||
width: number;
|
||||
height: number;
|
||||
commands: Array<
|
||||
| { moveTo: { x: number; y: number } }
|
||||
| { lineTo: { x: number; y: number } }
|
||||
| { quadBezTo: { x1: number; y1: number; x: number; y: number } }
|
||||
| { cubicBezTo: { x1: number; y1: number; x2: number; y2: number; x: number; y: number } }
|
||||
| { close: Record<string, never> }
|
||||
>;
|
||||
}>;
|
||||
};
|
||||
```
|
||||
|
||||
## Connector
|
||||
|
||||
```ts
|
||||
const connector = slide.shapes.connect(sourceShape, targetShape, {
|
||||
kind: "elbow",
|
||||
fromSide: "right",
|
||||
toSide: "left",
|
||||
line: { style: "solid", fill: "slate-400", width: 2 },
|
||||
head: { type: "arrow", width: "med", length: "med" },
|
||||
});
|
||||
```
|
||||
|
||||
Use [`connectors.md`](./connectors.md) for connector routing, side anchors,
|
||||
direct `geometry: "connector"` creation, arrowheads, and endpoint edits.
|
||||
|
||||
## Line Primitive Decision
|
||||
|
||||
| Need | Use |
|
||||
| --- | --- |
|
||||
| Divider inside compose JSX | `<rule stroke="slate-200" weight={1} />` |
|
||||
| Free-positioned line | `slide.shapes.add({ geometry: "line", position, fill: "none", line })` |
|
||||
| Freeform curve with Bézier control points | `slide.shapes.add({ geometry: "custom", position, fill: "none", line, customPaths })` |
|
||||
| Arrow connected to shapes | `slide.shapes.connect(fromShape, toShape, { line, head })` |
|
||||
| Border around a surface | shape or box `line={{ style: "solid", fill: "slate-200", width: 1 }}` |
|
||||
|
||||
## Shadows
|
||||
|
||||
Supported shadow tokens:
|
||||
|
||||
```text
|
||||
shadow-none, shadow-sm, shadow, shadow-md, shadow-lg, shadow-xl, shadow-2xl
|
||||
```
|
||||
|
||||
Custom shadow strings are also supported when the presentation has a theme
|
||||
context:
|
||||
|
||||
```ts
|
||||
shape.shadow = "shadow-md";
|
||||
shape.shadow = "2px 7px 19px #000000/17";
|
||||
shape.shadow = "shadow-none";
|
||||
```
|
||||
|
||||
## Ordering
|
||||
|
||||
```ts
|
||||
shape.bringToFront();
|
||||
shape.bringForward();
|
||||
shape.sendToBack();
|
||||
shape.sendBackward();
|
||||
```
|
||||
|
||||
These inherited methods also apply to images, tables, charts, embedded workbooks, and SmartArt. Forward/backward moves one position in the owning surface’s stack; front/back moves to an end.
|
||||
|
||||
## Cookbook
|
||||
|
||||
```ts
|
||||
// KPI metric surface.
|
||||
const metricSurface = slide.shapes.add({
|
||||
geometry: "roundRect",
|
||||
name: "kpi-surface",
|
||||
position: { left: 64, top: 132, width: 260, height: 148 },
|
||||
fill: "white",
|
||||
line: { style: "solid", fill: "slate-200", width: 1 },
|
||||
borderRadius: "rounded-2xl",
|
||||
shadow: "shadow-md",
|
||||
});
|
||||
metricSurface.text = "Revenue\n$12.4M";
|
||||
metricSurface.text.style = {
|
||||
className: "text-slate-950 text-2xl font-bold leading-tight",
|
||||
};
|
||||
```
|
||||
|
||||
```ts
|
||||
// Pill label.
|
||||
const pill = slide.shapes.add({
|
||||
geometry: "roundRect",
|
||||
position: { left: 64, top: 64, width: 148, height: 34 },
|
||||
fill: "emerald-50",
|
||||
line: { style: "solid", fill: "emerald-200", width: 1 },
|
||||
borderRadius: "rounded-full",
|
||||
});
|
||||
pill.text = "ON TRACK";
|
||||
pill.text.style = { className: "text-emerald-800 text-sm font-bold" };
|
||||
```
|
||||
|
||||
```ts
|
||||
// Directional connector between two shapes.
|
||||
slide.shapes.connect(sourceShape, targetShape, {
|
||||
kind: "elbow",
|
||||
fromSide: "right",
|
||||
toSide: "left",
|
||||
line: { style: "solid", fill: "slate-400", width: 2 },
|
||||
head: { type: "triangle", width: "sm", length: "sm" },
|
||||
});
|
||||
```
|
||||
Generated
Vendored
+199
@@ -0,0 +1,199 @@
|
||||
# Slide Facade
|
||||
|
||||
## Slide Show Visibility
|
||||
|
||||
```ts
|
||||
slide.hidden = isHidden;
|
||||
```
|
||||
|
||||
Hidden slides stay in the deck but are skipped during a slide show.
|
||||
|
||||
## Content Collections
|
||||
|
||||
```ts
|
||||
const shape = slide.shapes.add(shapeConfig);
|
||||
const image = slide.images.add(imageConfig);
|
||||
const table = slide.tables.add(tableConfig);
|
||||
const chart = slide.charts.add(chartType, chartConfig);
|
||||
```
|
||||
|
||||
## Content Config Pointers
|
||||
|
||||
```ts
|
||||
type ShapeConfig = PresetShapeConfig | CustomShapeConfig | ConnectorConfig; // see shapes.spec.md
|
||||
type ImageConfig = ImageAddOptions; // see images.spec.md
|
||||
type TableConfig = TableAddOptions | TableCellValue[][]; // see tables.spec.md
|
||||
type ChartConfig = {
|
||||
position?: { left?: number; top?: number; width?: number; height?: number };
|
||||
title?: string;
|
||||
categories?: string[];
|
||||
series?: Array<{ name: string; values?: number[] }>;
|
||||
}; // see charts.spec.md for axes, legend, labels, and series styling
|
||||
```
|
||||
|
||||
## Background
|
||||
|
||||
```ts
|
||||
const slide = presentation.slides.add({ background: { fill: fillConfig } });
|
||||
slide.background.fill = fillConfig;
|
||||
```
|
||||
|
||||
`fillConfig` accepts theme color strings, hex strings, solid configs, gradient configs, pattern configs, and image-fill configs.
|
||||
|
||||
## Layouts And Placeholders
|
||||
|
||||
```ts
|
||||
slide.setLayout(layout);
|
||||
|
||||
const placeholder = slide.placeholders.getItem(placeholderName);
|
||||
placeholder.text = placeholderText;
|
||||
placeholder.text.style = placeholderStyleName;
|
||||
```
|
||||
|
||||
```ts
|
||||
const actualPlaceholders = slide.placeholders.items;
|
||||
const emptyContentPlaceholders = slide.placeholders.editable;
|
||||
const allVisibleEmptyPlaceholders = slide.placeholders.unfilled;
|
||||
const missingLayoutSlots = slide.placeholders.availableFromLayout;
|
||||
const createdPlaceholders = slide.placeholders.addFromLayout();
|
||||
```
|
||||
|
||||
## Frame And Export
|
||||
|
||||
```ts
|
||||
const frame = slide.frame;
|
||||
const preview = await slide.export({ format, scale });
|
||||
const pdf = await slide.export({ format: "pdf" });
|
||||
```
|
||||
|
||||
## Compose Layout
|
||||
|
||||
```tsx
|
||||
/** @jsxRuntime automatic */
|
||||
|
||||
slide.compose(
|
||||
<row width="fill" height="fill" gap={20}>
|
||||
<column width={340} height="fill" gap={12}>
|
||||
<paragraph name="summary" className="text-slate-950 text-3xl font-bold">
|
||||
Summary
|
||||
</paragraph>
|
||||
<paragraph className="text-slate-600 text-sm">
|
||||
Compose-first layouts stay readable and export cleanly.
|
||||
</paragraph>
|
||||
</column>
|
||||
<box name="surface" width="fill" height="fill" padding={16} fill="#ffffff">
|
||||
<column height="fill" gap={10}>
|
||||
<rule stroke="#0f172a" weight={2} />
|
||||
</column>
|
||||
</box>
|
||||
</row>,
|
||||
{
|
||||
frame: { left: 48, top: 40, width: 864, height: 460 },
|
||||
baseUnit: 8,
|
||||
},
|
||||
);
|
||||
```
|
||||
|
||||
`slide.compose(...)` accepts either compose helper nodes or a JSX-authored tree.
|
||||
It still returns the materialized elements. Use `name` on materializing nodes
|
||||
when the slide needs stable inspect or layout-export anchors.
|
||||
|
||||
## Export Inline Type
|
||||
|
||||
```ts
|
||||
type SlideExportOptions = {
|
||||
format?: "png" | "jpeg" | "webp" | "pdf" | "layout";
|
||||
width?: number;
|
||||
height?: number;
|
||||
scale?: number;
|
||||
quality?: number;
|
||||
};
|
||||
```
|
||||
|
||||
`format: "layout"` exports the composed layout tree alongside the materialized slide elements. That is the most useful export when you need stable names, hierarchy paths, and resolved text for follow-up targeting.
|
||||
|
||||
## Auto Layout
|
||||
|
||||
```ts
|
||||
slide.autoLayout(shapes, {
|
||||
direction,
|
||||
frame,
|
||||
align,
|
||||
horizontalGap,
|
||||
verticalGap,
|
||||
horizontalPadding,
|
||||
verticalPadding,
|
||||
});
|
||||
```
|
||||
|
||||
## Auto Layout Inline Type
|
||||
|
||||
```ts
|
||||
type AutoLayoutOptions = {
|
||||
direction?: "horizontal" | "vertical";
|
||||
frame?:
|
||||
| "slide"
|
||||
| Shape
|
||||
| { left: number; top: number; width: number; height: number };
|
||||
align?:
|
||||
| "center"
|
||||
| "topLeft"
|
||||
| "topCenter"
|
||||
| "topRight"
|
||||
| "left"
|
||||
| "right"
|
||||
| "bottomLeft"
|
||||
| "bottomCenter"
|
||||
| "bottomRight";
|
||||
horizontalGap?: number | "auto";
|
||||
verticalGap?: number | "auto";
|
||||
horizontalPadding?: number;
|
||||
verticalPadding?: number;
|
||||
};
|
||||
```
|
||||
|
||||
## Speaker Notes
|
||||
|
||||
```ts
|
||||
slide.speakerNotes.text = notesText;
|
||||
slide.speakerNotes.setVisible(visible);
|
||||
```
|
||||
|
||||
## Visual QA Loop
|
||||
|
||||
```ts
|
||||
const preview = await slide.export({ format: "png", scale: 2 });
|
||||
const layout = await slide.export({ format: "layout" });
|
||||
const after = await presentation.inspect({
|
||||
kind: "slide,textbox,shape,image,table,chart,notes",
|
||||
target: { id: slideAnchorId, beforeLines: 2, afterLines: 8 },
|
||||
maxChars: 4000,
|
||||
});
|
||||
```
|
||||
|
||||
Check the PNG for clipping, overlap, weak contrast, illegible text, bad image
|
||||
crops, accidental rasterized labels, and off-canvas elements. Check the layout
|
||||
export or inspect output for stable `name` values on important nodes.
|
||||
|
||||
## Cookbook
|
||||
|
||||
```ts
|
||||
// Gradient background plus editable content.
|
||||
slide.background.fill = "linear(180deg, slate-950 0%, blue-950 100%)";
|
||||
const title = slide.shapes.add({
|
||||
geometry: "textbox",
|
||||
name: "title",
|
||||
position: { left: 72, top: 72, width: 760, height: 120 },
|
||||
fill: "none",
|
||||
line: { style: "solid", fill: "none", width: 0 },
|
||||
});
|
||||
title.text = "Editable headline";
|
||||
title.text.style = { fontSize: 44, bold: true, color: "white" };
|
||||
```
|
||||
|
||||
```ts
|
||||
// Clone rhythm from another slide, then change content.
|
||||
const next = sourceSlide.duplicate();
|
||||
next.moveTo(3);
|
||||
next.placeholders.getItem("title").text = "Updated section title";
|
||||
```
|
||||
Generated
Vendored
+48
@@ -0,0 +1,48 @@
|
||||
# Speaker Notes
|
||||
|
||||
Speaker notes live on `slide.speakerNotes`.
|
||||
|
||||
## Set Text
|
||||
|
||||
```ts
|
||||
const speakerNotes = slide.speakerNotes;
|
||||
speakerNotes.text = notesText;
|
||||
const savedText = speakerNotes.text;
|
||||
```
|
||||
|
||||
## Notes Text Inline Type
|
||||
|
||||
```ts
|
||||
type NotesTextValue = string | string[] | StructuredTextInput;
|
||||
|
||||
type TextRunInput = {
|
||||
run: string;
|
||||
style?: { bold?: boolean; italic?: boolean; fontSize?: string; color?: FillConfig };
|
||||
textStyle?: TextRunInput["style"]; // Compatibility alias.
|
||||
};
|
||||
```
|
||||
|
||||
## Visibility And Clearing
|
||||
|
||||
```ts
|
||||
speakerNotes.setVisible(visible);
|
||||
const visibleState = speakerNotes.isVisible();
|
||||
speakerNotes.clear();
|
||||
```
|
||||
|
||||
## Cookbook
|
||||
|
||||
```ts
|
||||
// Structured presenter notes.
|
||||
slide.speakerNotes.text = [
|
||||
"Open with the customer problem, not the feature list.",
|
||||
"Call out the chart source before discussing the slope.",
|
||||
"Pause for questions before the implementation timeline.",
|
||||
];
|
||||
slide.speakerNotes.setVisible(true);
|
||||
```
|
||||
|
||||
```ts
|
||||
// Append without deleting imported notes.
|
||||
slide.speakerNotes.append("\nFollow-up: confirm launch date with PM.");
|
||||
```
|
||||
Generated
Vendored
+85
@@ -0,0 +1,85 @@
|
||||
# Named Text Styles
|
||||
|
||||
`presentation.styles` stores reusable text styles for shapes and text ranges.
|
||||
|
||||
## Style Surface Map
|
||||
|
||||
| Need | API |
|
||||
| --- | --- |
|
||||
| Deck-level tokenized text style ids | `presentation.theme.textStyles({...})` |
|
||||
| Slide-scoped generated text style ids | `slide.theme.textStyles({...})` |
|
||||
| Explicit named styles by facade | `presentation.styles.add(name)` |
|
||||
|
||||
## Built-In Styles
|
||||
|
||||
```ts
|
||||
const styles = presentation.styles;
|
||||
const style = styles.get(styleName);
|
||||
const summary = styles.describe(styleName);
|
||||
const allStyles = styles.describe();
|
||||
```
|
||||
|
||||
## Custom Style
|
||||
|
||||
```ts
|
||||
const custom = presentation.styles.add(styleName);
|
||||
custom.description = styleDescription;
|
||||
custom.color = styleColor;
|
||||
custom.bold = isBold;
|
||||
custom.italic = isItalic;
|
||||
custom.fontSize = fontSizePx;
|
||||
custom.alignment = alignment;
|
||||
```
|
||||
|
||||
## Named Style Facade Fields
|
||||
|
||||
```ts
|
||||
type NamedStyleFacade = {
|
||||
description?: string;
|
||||
usageHint?: string;
|
||||
bold?: boolean;
|
||||
italic?: boolean;
|
||||
fontSize?: number;
|
||||
alignment?: "left" | "center" | "right" | "justify";
|
||||
underline?: string;
|
||||
color?: ColorConfig;
|
||||
};
|
||||
```
|
||||
|
||||
Use broader `TextStyleConfig` objects on `shape.text.style = { ... }`,
|
||||
`presentation.theme.textStyles(...)`, and `slide.theme.textStyles(...)`.
|
||||
|
||||
## Use A Style
|
||||
|
||||
```ts
|
||||
shape.text = textValue;
|
||||
shape.text.style = styleName;
|
||||
|
||||
const range = shape.text.get(rangeText);
|
||||
range.style = styleName;
|
||||
```
|
||||
|
||||
Named styles are block-level for paragraph style assignments and range-level for selected text ranges.
|
||||
|
||||
## Cookbook
|
||||
|
||||
```ts
|
||||
// Deck-level type scale.
|
||||
const display = presentation.styles.add("Display");
|
||||
display.fontSize = 52;
|
||||
display.bold = true;
|
||||
display.color = "#0f172a";
|
||||
display.usageHint = "Hero and section titles";
|
||||
|
||||
const body = presentation.styles.add("Body");
|
||||
body.fontSize = 20;
|
||||
body.color = "#475569";
|
||||
body.usageHint = "Readable body copy";
|
||||
```
|
||||
|
||||
```ts
|
||||
// Apply a style, then emphasize one range.
|
||||
shape.text = "Revenue accelerated across enterprise accounts.";
|
||||
shape.text.style = "Body";
|
||||
shape.text.get("Revenue").style = "Display";
|
||||
```
|
||||
Generated
Vendored
+198
@@ -0,0 +1,198 @@
|
||||
# Tables
|
||||
|
||||
`slide.tables` creates and edits PowerPoint-style tables.
|
||||
|
||||
## Resolved From Inspect
|
||||
|
||||
```ts
|
||||
const table = presentation.resolve("tb/d4e5f6a7");
|
||||
table.cells.set(1, 2, "$4.2M");
|
||||
table.getCell(1, 2).text.style = "Body Small";
|
||||
table.borders.assign({ style: "solid", fill: "slate-200", width: 1 });
|
||||
```
|
||||
|
||||
Use `presentation.inspect({ kind: "table", search })` to find the `tb/...`
|
||||
anchor id. If an imported table resolves as an image, preserve it as an image or
|
||||
rebuild it as a native table intentionally.
|
||||
|
||||
## Add Table
|
||||
|
||||
```ts
|
||||
const table = slide.tables.add({
|
||||
rows,
|
||||
columns,
|
||||
left,
|
||||
top,
|
||||
width,
|
||||
height,
|
||||
columnTracks: [fr(2), fr(1), fixed(120)],
|
||||
values,
|
||||
});
|
||||
```
|
||||
|
||||
Primitive matrices and structured text runs are accepted for `values`. Use `columnTracks` with `fr(...)` and `fixed(...)` when a table should fill its frame with proportional columns. Use `columnWidths` only for explicit pixel widths.
|
||||
|
||||
## Table Inline Types
|
||||
|
||||
```ts
|
||||
type TableAddOptions = {
|
||||
rows: number;
|
||||
columns: number;
|
||||
left?: number;
|
||||
top?: number;
|
||||
width?: number;
|
||||
height?: number;
|
||||
values?: TableCellValue[][];
|
||||
columnTracks?: TableColumnTrack[];
|
||||
columnWidths?: number[];
|
||||
};
|
||||
|
||||
type TableColumnTrack =
|
||||
| { mode: "fr"; value: number }
|
||||
| { mode: "fixed"; value: number };
|
||||
|
||||
type TableCellValue = string | number | string[] | StructuredTextInput | Text;
|
||||
```
|
||||
|
||||
## Cells
|
||||
|
||||
```ts
|
||||
const cell = table.getCell(rowIndex, columnIndex);
|
||||
cell.value = cellValue;
|
||||
cell.fill = fillConfig;
|
||||
cell.text.style = textStyleName;
|
||||
|
||||
table.cells.set(rowIndex, columnIndex, textObjectOrValue);
|
||||
```
|
||||
|
||||
## Ranges And Merges
|
||||
|
||||
```ts
|
||||
table.merge({
|
||||
startRow,
|
||||
endRow,
|
||||
startColumn,
|
||||
endColumn,
|
||||
});
|
||||
|
||||
const range = table.cells.block(rangeConfig);
|
||||
range.fill = fillConfig;
|
||||
range.textStyle.bold = isBold;
|
||||
range.textStyle.color = textColor;
|
||||
range.textStyle.fontSize = fontSizePx;
|
||||
range.borders = borderConfig;
|
||||
|
||||
table.unmerge({ startRow, endRow, startColumn, endColumn });
|
||||
```
|
||||
|
||||
## Insert And Delete Rows Or Columns
|
||||
|
||||
```ts
|
||||
table.insertRows({ index: rowIndex, count: 2 });
|
||||
table.deleteRows({ index: rowIndex, count: 1 });
|
||||
table.insertColumns({ index: columnIndex });
|
||||
table.deleteColumns({ index: columnIndex });
|
||||
```
|
||||
|
||||
## Range And Merge Inline Types
|
||||
|
||||
```ts
|
||||
type TableMergeRange = {
|
||||
startRow: number;
|
||||
endRow: number;
|
||||
startColumn: number;
|
||||
endColumn: number;
|
||||
};
|
||||
|
||||
type TableCellRangeConfig = {
|
||||
row: number;
|
||||
column: number;
|
||||
rowCount: number;
|
||||
columnCount: number;
|
||||
};
|
||||
```
|
||||
|
||||
## Style
|
||||
|
||||
```ts
|
||||
table.style = tableStyleId;
|
||||
table.styleOptions = tableStyleOptions;
|
||||
table.columnTracks = [fr(2), fr(1), fixed(120)];
|
||||
table.rows[0].height = headerHeightPx;
|
||||
table.columns.get(columnIndex).width = columnWidthPx;
|
||||
table.borders.assign(borderConfig);
|
||||
|
||||
table.cells.block({ row, column, rowCount, columnCount }).assign({
|
||||
fill,
|
||||
textStyle,
|
||||
borders,
|
||||
margins,
|
||||
anchor,
|
||||
horizontalOverflow,
|
||||
});
|
||||
```
|
||||
|
||||
## Style Inline Types
|
||||
|
||||
```ts
|
||||
type TableStyleOptions = {
|
||||
headerRow?: boolean;
|
||||
totalRow?: boolean;
|
||||
firstColumn?: boolean;
|
||||
lastColumn?: boolean;
|
||||
bandedRows?: boolean;
|
||||
bandedColumns?: boolean;
|
||||
};
|
||||
|
||||
type TableBorderLineConfig = {
|
||||
style?: "solid" | "dashed" | "dotted" | "dash-dot" | "dash-dot-dot" | string;
|
||||
width?: number;
|
||||
fill?: FillConfig;
|
||||
color?: FillConfig;
|
||||
};
|
||||
```
|
||||
|
||||
## Cookbook
|
||||
|
||||
```ts
|
||||
// Compact KPI table.
|
||||
const table = slide.tables.add({
|
||||
rows: 4,
|
||||
columns: 3,
|
||||
left: 96,
|
||||
top: 168,
|
||||
width: 680,
|
||||
height: 220,
|
||||
values: [
|
||||
["Metric", "Current", "Delta"],
|
||||
["Revenue", "$12.4M", "+18%"],
|
||||
["Retention", "94%", "+3 pts"],
|
||||
["Latency", "182 ms", "-22 ms"],
|
||||
],
|
||||
});
|
||||
table.styleOptions = { headerRow: true, bandedRows: true };
|
||||
table.getCell(0, 0).fill = "slate-950";
|
||||
table.getCell(0, 1).fill = "slate-950";
|
||||
table.getCell(0, 2).fill = "slate-950";
|
||||
table.borders.assign({ style: "solid", fill: "slate-200", width: 1 });
|
||||
```
|
||||
|
||||
```ts
|
||||
// Spanning title row.
|
||||
table.merge({ startRow: 0, endRow: 0, startColumn: 0, endColumn: 2 });
|
||||
table.getCell(0, 0).value = "Regional performance";
|
||||
table.getCell(0, 0).text.style = "title";
|
||||
```
|
||||
|
||||
```ts
|
||||
// Highlight a cell range.
|
||||
const riskRange = table.cells.block({
|
||||
row: 2,
|
||||
column: 2,
|
||||
rowCount: 2,
|
||||
columnCount: 1,
|
||||
});
|
||||
riskRange.fill = "amber-50";
|
||||
riskRange.textStyle.color = "#92400e";
|
||||
riskRange.textStyle.bold = true;
|
||||
```
|
||||
Generated
Vendored
+97
@@ -0,0 +1,97 @@
|
||||
# Theme
|
||||
|
||||
Themes provide default fonts, named colors, and text style tokens.
|
||||
|
||||
## Default Font
|
||||
|
||||
```ts
|
||||
presentation.theme.defaultFont = "Aptos";
|
||||
```
|
||||
|
||||
New presentations default to Aptos. Set `defaultFont: string` once during setup
|
||||
to choose the theme's Latin heading and body font. Shape text with no explicit
|
||||
`typeface` inherits the theme; a local `typeface` overrides it. The choice persists with
|
||||
the presentation. Imported presentations retain their existing font schemes;
|
||||
changing `defaultFont` preserves language-specific font mappings.
|
||||
|
||||
## Color Scheme
|
||||
|
||||
```ts
|
||||
presentation.theme.colorScheme = {
|
||||
name: themeName,
|
||||
themeColors,
|
||||
};
|
||||
|
||||
const hexMap = presentation.theme.hexColorMap;
|
||||
```
|
||||
|
||||
`themeColors` maps every theme color name to a color config value. Assigning
|
||||
`presentation.theme.colorScheme` replaces the active scheme, so provide the
|
||||
full map.
|
||||
|
||||
## Color Scheme Inline Type
|
||||
|
||||
```ts
|
||||
type ThemeColorName =
|
||||
| "accent1" | "accent2" | "accent3" | "accent4" | "accent5" | "accent6"
|
||||
| "bg1" | "bg2" | "tx1" | "tx2" | "dk1" | "lt1" | "dk2" | "lt2"
|
||||
| "hlink" | "folHlink";
|
||||
|
||||
type ColorSchemeConfig = {
|
||||
name: string;
|
||||
themeColors: Record<ThemeColorName, ColorConfig>;
|
||||
};
|
||||
```
|
||||
|
||||
## Theme Colors In Content
|
||||
|
||||
```ts
|
||||
const shape = slide.shapes.add({
|
||||
geometry,
|
||||
position,
|
||||
fill: themeColorName,
|
||||
line: { style: lineStyle, fill: lineColor, width: lineWidthPx },
|
||||
});
|
||||
```
|
||||
|
||||
## Text Styles
|
||||
|
||||
```ts
|
||||
const styles = slide.theme.textStyles({
|
||||
[styleName]: textStyleConfig,
|
||||
});
|
||||
```
|
||||
|
||||
## Cookbook
|
||||
|
||||
```ts
|
||||
// Business/product palette.
|
||||
presentation.theme.colorScheme = {
|
||||
name: "Product Editorial",
|
||||
themeColors: {
|
||||
accent1: "#2563eb",
|
||||
accent2: "#0f766e",
|
||||
accent3: "#f59e0b",
|
||||
accent4: "#dc2626",
|
||||
accent5: "#7c3aed",
|
||||
accent6: "#16a34a",
|
||||
bg1: "#ffffff",
|
||||
bg2: "#f8fafc",
|
||||
tx1: "#0f172a",
|
||||
tx2: "#475569",
|
||||
dk1: "#000000",
|
||||
dk2: "#1e293b",
|
||||
lt1: "#ffffff",
|
||||
lt2: "#e2e8f0",
|
||||
hlink: "#2563eb",
|
||||
folHlink: "#7c3aed",
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
```ts
|
||||
// Use theme tokens in content so later theme changes flow through.
|
||||
slide.background.fill = "bg1";
|
||||
shape.fill = "accent1";
|
||||
shape.text.style = { color: "tx1" };
|
||||
```
|
||||
Generated
Vendored
+447
@@ -0,0 +1,447 @@
|
||||
# Presentation Token Reference
|
||||
|
||||
This reference covers the Tailwind-like tokens supported by presentation
|
||||
shapes, text, and JSX. These are presentation tokens, not browser CSS.
|
||||
|
||||
## Where Tokens Work
|
||||
|
||||
| Surface | Token entry |
|
||||
| --- | --- |
|
||||
| Shape/box fill | `fill="sky-500"`, `fill="rose-500/80"` |
|
||||
| Shape/box line | `line={{ style: "solid", fill: "slate-200", width: 1 }}` |
|
||||
| Shape/box radius | `borderRadius="rounded-xl"` |
|
||||
| Image radius | `borderRadius="rounded-2xl"` |
|
||||
| Shape shadow | `shadow="shadow-md"` |
|
||||
| Shape/box className | `className="bg-white rounded-xl shadow-sm"` |
|
||||
| Text className | `className="text-slate-700 text-lg font-bold leading-tight"` |
|
||||
| Imperative shape | `shape.className = "bg-sky-50 rounded-lg shadow"` |
|
||||
| Imperative text | `shape.text.style = { className: "text-slate-800 text-xl leading-relaxed" }` |
|
||||
| Text range | `shape.text.get("Total").className = "text-emerald-600 font-bold"` |
|
||||
|
||||
Explicit props override `className` on JSX nodes. For example,
|
||||
`<box className="bg-slate-900" fill="white" />` uses the explicit `fill`.
|
||||
`className` is only for visual/text tokens. Use real JSX props for layout:
|
||||
`width`, `height`, `gap`, `padding`, `align`, and `justify`.
|
||||
|
||||
## Decision Table
|
||||
|
||||
| Need | Use |
|
||||
| --- | --- |
|
||||
| Common shape styling | `className="bg-white rounded-xl shadow-sm"` |
|
||||
| Exact fill or gradient | `fill="#0f172a"` or `fill="linear(135deg, #fff 0%, sky-100 100%)"` |
|
||||
| Exact line | `line={{ style: "solid", fill: "slate-200", width: 1 }}` |
|
||||
| Common text styling | `className="text-slate-700 text-lg font-bold leading-tight"` |
|
||||
| Exact text style | `style="font: 700 22px Inter; color: #334155; leading: 1.25; wrap: none"` |
|
||||
| Inline emphasis | `<run textStyle={{ bold: true, color: "sky-600" }}>...</run>` |
|
||||
| Layout | real props such as `gap={24}`, `padding={{ x: 32, y: 24 }}`, `align="center"` |
|
||||
|
||||
## Token Cookbook
|
||||
|
||||
Transparent overlay:
|
||||
|
||||
```tsx
|
||||
<shape geometry="rect" width="fill" height="fill" fill="black/45" />
|
||||
<paragraph className="text-white/80 text-xl">Readable over an image</paragraph>
|
||||
```
|
||||
|
||||
Theme color with a transform:
|
||||
|
||||
```tsx
|
||||
<box fill="accent1+18/90" />
|
||||
<paragraph style="font: 700 18px Inter; color: tx1-10/85; wrap: none">
|
||||
Theme-aware text
|
||||
</paragraph>
|
||||
```
|
||||
|
||||
`+` lightens, `-` darkens, and `/` sets opacity. The suffix accepts unit
|
||||
fractions, numbers, or percentages: `accent1+0.18/0.9`, `accent1+18/90`, and
|
||||
`accent1+18%/90%` are equivalent.
|
||||
|
||||
Soft surface with exact line:
|
||||
|
||||
```tsx
|
||||
<box
|
||||
fill="slate-50"
|
||||
line={{ style: "solid", fill: "slate-200", width: 1 }}
|
||||
borderRadius="rounded-2xl"
|
||||
shadow="shadow-sm"
|
||||
/>
|
||||
```
|
||||
|
||||
No fill, visible stroke:
|
||||
|
||||
```tsx
|
||||
<shape
|
||||
geometry="ellipse"
|
||||
fill="none"
|
||||
line={{ style: "dashed", fill: "sky-500/70", width: 2 }}
|
||||
width={96}
|
||||
height={96}
|
||||
/>
|
||||
```
|
||||
|
||||
Gradient background plus transparent edge:
|
||||
|
||||
```tsx
|
||||
<box fill="linear(135deg, #ffffff 0%, sky-100 58%, #ffffff/0 100%)" />
|
||||
```
|
||||
|
||||
Radial highlight:
|
||||
|
||||
```tsx
|
||||
<shape
|
||||
geometry="ellipse"
|
||||
fill="radial(white/80 0%, emerald-200/45 48%, emerald-700/0 100%)"
|
||||
width={420}
|
||||
height={260}
|
||||
/>
|
||||
```
|
||||
|
||||
Custom shadow:
|
||||
|
||||
```tsx
|
||||
<box fill="white" borderRadius="rounded-2xl" shadow="2px 7px 19px #000000/17" />
|
||||
```
|
||||
|
||||
Exact text style string:
|
||||
|
||||
```tsx
|
||||
<paragraph style="font: 700 24px Inter; color: #334155; leading: 1.2; wrap: none">
|
||||
One-line label
|
||||
</paragraph>
|
||||
```
|
||||
|
||||
Tokenized text with arbitrary size and leading:
|
||||
|
||||
```tsx
|
||||
<paragraph className="text-slate-950 text-[32px] font-bold leading-[1.12]">
|
||||
Precise headline
|
||||
</paragraph>
|
||||
```
|
||||
|
||||
## Color Tokens
|
||||
|
||||
Color tokens can be used directly as fill/color strings or through `bg-*` and
|
||||
`text-*` class names.
|
||||
|
||||
```tsx
|
||||
<box fill="slate-950" line={{ style: "solid", fill: "slate-700", width: 1 }} />
|
||||
<box className="bg-sky-50 rounded-xl shadow-sm" />
|
||||
<paragraph className="text-slate-700 text-lg">Readable text</paragraph>
|
||||
```
|
||||
|
||||
Alpha suffixes are supported:
|
||||
|
||||
```tsx
|
||||
<shape geometry="rect" fill="black/45" width="fill" height="fill" />
|
||||
<paragraph className="text-white/80 text-xl">Muted overlay text</paragraph>
|
||||
<box className="bg-rose-500/75 rounded-full" />
|
||||
```
|
||||
|
||||
Theme colors and aliases are supported as color strings:
|
||||
|
||||
```tsx
|
||||
<box fill="accent1" />
|
||||
<box fill="accent2+20/80" />
|
||||
<paragraph style="font: 600 18px Inter; color: text1/80; wrap: none">
|
||||
Uses the presentation theme text color
|
||||
</paragraph>
|
||||
```
|
||||
|
||||
Theme names:
|
||||
|
||||
```text
|
||||
accent1, accent2, accent3, accent4, accent5, accent6,
|
||||
bg1, bg2, tx1, tx2, dk1, dk2, lt1, lt2, hlink, folHlink
|
||||
```
|
||||
|
||||
Aliases:
|
||||
|
||||
```text
|
||||
background1 -> bg1
|
||||
background2 -> bg2
|
||||
text1 -> tx1
|
||||
text2 -> tx2
|
||||
dark1 -> dk1
|
||||
dark2 -> dk2
|
||||
light1 -> lt1
|
||||
light2 -> lt2
|
||||
```
|
||||
|
||||
Supported color names:
|
||||
|
||||
| Family | Tokens |
|
||||
| --- | --- |
|
||||
| Neutrals | `slate`, `gray`, `zinc`, `neutral`, `stone` |
|
||||
| Warm | `red`, `orange`, `amber`, `yellow`, `lime` |
|
||||
| Green/blue | `green`, `emerald`, `teal`, `cyan`, `sky`, `blue` |
|
||||
| Violet/pink | `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose` |
|
||||
| Additional muted sets | `mauve`, `mist`, `olive`, `taupe` |
|
||||
| Singletons | `black`, `white` |
|
||||
|
||||
For palette families, supported shades are:
|
||||
|
||||
```text
|
||||
50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950
|
||||
```
|
||||
|
||||
Use `family-shade`, for example `slate-50`, `slate-900`, `sky-500`,
|
||||
`emerald-700`, or `rose-950`.
|
||||
|
||||
Alpha values accept percent-like numbers, percentages, or unit fractions:
|
||||
|
||||
```text
|
||||
sky-500/80
|
||||
sky-500/80%
|
||||
sky-500/0.8
|
||||
black/10
|
||||
white/65
|
||||
```
|
||||
|
||||
Hex, short hex, RGB, RGBA, and `transparent` are accepted:
|
||||
|
||||
```tsx
|
||||
<box fill="#0F172A/12" />
|
||||
<box fill="#0F172A1F" />
|
||||
<box fill="rgb(15 23 42 / 12%)" />
|
||||
<box fill="rgba(15, 23, 42, 0.12)" />
|
||||
<shape geometry="rect" fill="transparent" />
|
||||
```
|
||||
|
||||
Use `fill="none"` when the object should have no fill. Use
|
||||
`fill="transparent"` or `#00000000` when the object should keep an editable
|
||||
transparent solid fill. Express transparent and no-fill cases with the explicit
|
||||
`fill` prop.
|
||||
|
||||
## Gradient Strings
|
||||
|
||||
Gradient fill strings are supported wherever `FillConfig` strings are accepted.
|
||||
Use them for editable vector backgrounds and surfaces:
|
||||
|
||||
```tsx
|
||||
<box fill="linear(135deg, #ffffff 0%, sky-100 55%, #ffffff/0 100%)" />
|
||||
<shape geometry="ellipse" fill="radial(#ffffff 0%, emerald-200 48%, emerald-700 100%)" />
|
||||
```
|
||||
|
||||
`linear(...)` accepts an optional angle first. `radial(...)` is a path gradient.
|
||||
Stops use color plus optional offset percentages.
|
||||
|
||||
Offsets are optional; when omitted, stops are distributed evenly:
|
||||
|
||||
```tsx
|
||||
<box fill="linear(slate-950, blue-800, sky-400)" />
|
||||
```
|
||||
|
||||
Use explicit offsets when a narrow band or fade matters:
|
||||
|
||||
```tsx
|
||||
<box fill="linear(90deg, black/80 0%, black/36 42%, black/0 100%)" />
|
||||
<shape geometry="ellipse" fill="radial(accent1+35/55 0%, accent1/12 58%, accent1/0 100%)" />
|
||||
```
|
||||
|
||||
## Shape Class Tokens
|
||||
|
||||
Shape and box `className` supports:
|
||||
|
||||
```text
|
||||
bg-*
|
||||
rounded
|
||||
rounded-none
|
||||
rounded-sm
|
||||
rounded-md
|
||||
rounded-lg
|
||||
rounded-xl
|
||||
rounded-2xl
|
||||
rounded-3xl
|
||||
rounded-full
|
||||
shadow-none
|
||||
shadow-sm
|
||||
shadow
|
||||
shadow-md
|
||||
shadow-lg
|
||||
shadow-xl
|
||||
shadow-2xl
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```tsx
|
||||
<box
|
||||
width="fill"
|
||||
height={180}
|
||||
className="bg-white rounded-xl shadow-md"
|
||||
line={{ style: "solid", fill: "slate-200", width: 1 }}
|
||||
/>
|
||||
```
|
||||
|
||||
Radius values:
|
||||
|
||||
| Token | Radius |
|
||||
| --- | ---: |
|
||||
| `rounded-none` | `0px` |
|
||||
| `rounded-sm` | `2px` |
|
||||
| `rounded` | `4px` |
|
||||
| `rounded-md` | `6px` |
|
||||
| `rounded-lg` | `8px` |
|
||||
| `rounded-xl` | `12px` |
|
||||
| `rounded-2xl` | `16px` |
|
||||
| `rounded-3xl` | `24px` |
|
||||
| `rounded-full` | `9999px` |
|
||||
|
||||
Shadow tokens:
|
||||
|
||||
```text
|
||||
shadow-none, shadow-sm, shadow, shadow-md, shadow-lg, shadow-xl, shadow-2xl
|
||||
```
|
||||
|
||||
Custom shadow strings are also supported on `shadow`:
|
||||
|
||||
```tsx
|
||||
<box shadow="2px 7px 19px #000000/17" />
|
||||
```
|
||||
|
||||
## Text Class Tokens
|
||||
|
||||
Text `className` supports color, size, weight, italic, and leading:
|
||||
|
||||
```tsx
|
||||
<paragraph className="text-slate-950 text-5xl font-bold leading-tight">
|
||||
Large headline
|
||||
</paragraph>
|
||||
<paragraph className="text-slate-600 text-lg leading-relaxed">
|
||||
Body copy with looser line spacing.
|
||||
</paragraph>
|
||||
```
|
||||
|
||||
Text sizes:
|
||||
|
||||
| Token | Size |
|
||||
| --- | ---: |
|
||||
| `text-xs` | `12px` |
|
||||
| `text-sm` | `14px` |
|
||||
| `text-base` | `16px` |
|
||||
| `text-lg` | `18px` |
|
||||
| `text-xl` | `20px` |
|
||||
| `text-2xl` | `24px` |
|
||||
| `text-3xl` | `30px` |
|
||||
| `text-4xl` | `36px` |
|
||||
| `text-5xl` | `48px` |
|
||||
| `text-6xl` | `60px` |
|
||||
| `text-[32px]` | arbitrary positive pixel size |
|
||||
|
||||
Font weight tokens:
|
||||
|
||||
| Bold flag | Tokens |
|
||||
| --- | --- |
|
||||
| `true` | `font-semibold`, `font-bold`, `font-black` |
|
||||
| `false` | `font-thin`, `font-extralight`, `font-light`, `font-normal`, `font-medium`, `font-extrabold` |
|
||||
|
||||
Font weight maps to a boolean bold flag, not numeric weights. Use only
|
||||
`font-semibold`, `font-bold`, or `font-black` when the text should be bold. Use
|
||||
`font-normal` when the text should not be bold. `font-extrabold` maps to the
|
||||
non-bold side because exact `500`/`600`/`700`/`800` differences are not
|
||||
preserved.
|
||||
|
||||
`italic` sets italic text.
|
||||
|
||||
Leading tokens:
|
||||
|
||||
| Token | Line spacing |
|
||||
| --- | ---: |
|
||||
| `leading-none` | `1` |
|
||||
| `leading-tight` | `1.25` |
|
||||
| `leading-snug` | `1.375` |
|
||||
| `leading-normal` | `1.5` |
|
||||
| `leading-relaxed` | `1.625` |
|
||||
| `leading-loose` | `2` |
|
||||
| `leading-3` through `leading-10` | `12px` through `40px`, converted against current font size |
|
||||
| `leading-[1.35]` | arbitrary multiplier |
|
||||
| `leading-[150%]` | percentage multiplier |
|
||||
| `leading-[28px]` | absolute pixels, converted against current font size |
|
||||
|
||||
When using absolute leading such as `leading-7` or `leading-[28px]`, put the
|
||||
text size token before the leading token in the class string so conversion uses
|
||||
the intended font size:
|
||||
|
||||
```tsx
|
||||
<paragraph className="text-2xl leading-8">24px text with 32px leading</paragraph>
|
||||
```
|
||||
|
||||
## Direct Props Versus Class Names
|
||||
|
||||
Use direct props when a value is part of the object schema:
|
||||
|
||||
```tsx
|
||||
<shape
|
||||
geometry="rect"
|
||||
fill="emerald-500"
|
||||
line={{ style: "solid", fill: "emerald-700", width: 1 }}
|
||||
borderRadius="rounded-lg"
|
||||
shadow="shadow-sm"
|
||||
width={160}
|
||||
height={96}
|
||||
/>
|
||||
```
|
||||
|
||||
Use `className` when grouping common style tokens:
|
||||
|
||||
```tsx
|
||||
<box className="bg-emerald-50 rounded-xl shadow-sm">
|
||||
<paragraph className="text-emerald-900 text-xl font-bold leading-tight">
|
||||
Compact token styling
|
||||
</paragraph>
|
||||
</box>
|
||||
```
|
||||
|
||||
Use object `style` for exact text settings that tokens do not cover:
|
||||
|
||||
```tsx
|
||||
<paragraph
|
||||
style={{
|
||||
typeface: "Aptos",
|
||||
fontSize: 22,
|
||||
color: "slate-700",
|
||||
alignment: "center",
|
||||
lineSpacing: 1.2,
|
||||
}}
|
||||
>
|
||||
Exact text config
|
||||
</paragraph>
|
||||
```
|
||||
|
||||
Use a compact style string when the exact settings fit on one line:
|
||||
|
||||
```tsx
|
||||
<paragraph style="font: italic 600 20px Aptos; color: slate-700; leading: 1.25; align: center">
|
||||
Compact exact text config
|
||||
</paragraph>
|
||||
```
|
||||
|
||||
Supported text style declarations:
|
||||
|
||||
```text
|
||||
font, size, font-size, family, font-family, typeface,
|
||||
weight, font-weight, italic, font-style, color, fill,
|
||||
leading, align, alignment, wrap, underline, inset, insets,
|
||||
padding, autofit, auto-fit
|
||||
```
|
||||
|
||||
Use `leading`, not `line-height`, in style strings.
|
||||
|
||||
## ClassName Scope
|
||||
|
||||
The token parser covers visual and text styling. JSX layout props represent
|
||||
layout utilities such as padding, gap, width, height, flex flow, grid flow,
|
||||
alignment, and distribution:
|
||||
|
||||
```tsx
|
||||
<row width="fill" height="fill" gap={24} align="center" justify="between" />
|
||||
<box padding={{ x: 32, y: 24 }} line={{ style: "solid", fill: "slate-200", width: 1 }} />
|
||||
```
|
||||
|
||||
## Source References
|
||||
|
||||
- `src/models/presentation/utils/tailwind/*.ts`: token parsers.
|
||||
- `src/models/presentation/utils/tailwind/tailwind-colors.generated.ts`: full
|
||||
color token map.
|
||||
- `tests/presentation/tailwind-tokens.sanity.spec.ts`: visual token coverage.
|
||||
Reference in New Issue
Block a user