@sanity-labs/slides 0.0.0

package/src/core/__snapshots__/reconciler.test.ts.snap

@@ -0,0 +1,320 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`renderToOps — Box fill > a Box with both fill and text emits fill *before* insertText > ops 1`] = `
+[
+  {
+    "insertAt": 0,
+    "slideId": "slide_1",
+    "type": "createSlide",
+  },
+  {
+    "rect": {
+      "h": 1270000,
+      "w": 7620000,
+      "x": 685800,
+      "y": 685800,
+    },
+    "shape": "TEXT_BOX",
+    "shapeId": "shape_2",
+    "slideId": "slide_1",
+    "type": "createShape",
+  },
+  {
+    "objectId": "shape_2",
+    "properties": {
+      "fillColor": "#0b0b0b",
+    },
+    "type": "updateShapeProperties",
+  },
+  {
+    "objectId": "shape_2",
+    "text": "Hello",
+    "type": "insertText",
+  },
+]
+`;
+
+exports[`renderToOps — Box fill > an empty Box with a solid fill emits createShape → updateShapeProperties (no text ops) > ops 1`] = `
+[
+  {
+    "insertAt": 0,
+    "slideId": "slide_1",
+    "type": "createSlide",
+  },
+  {
+    "rect": {
+      "h": 6858000,
+      "w": 12192000,
+      "x": 0,
+      "y": 0,
+    },
+    "shape": "TEXT_BOX",
+    "shapeId": "shape_2",
+    "slideId": "slide_1",
+    "type": "createShape",
+  },
+  {
+    "objectId": "shape_2",
+    "properties": {
+      "fillColor": "#ff5500",
+    },
+    "type": "updateShapeProperties",
+  },
+]
+`;
+
+exports[`renderToOps — Box-level styles > Box textStyle and paragraphStyle become full-range update ops > ops 1`] = `
+[
+  {
+    "insertAt": 0,
+    "slideId": "slide_1",
+    "type": "createSlide",
+  },
+  {
+    "rect": {
+      "h": 1270000,
+      "w": 7620000,
+      "x": 685800,
+      "y": 685800,
+    },
+    "shape": "TEXT_BOX",
+    "shapeId": "shape_2",
+    "slideId": "slide_1",
+    "type": "createShape",
+  },
+  {
+    "objectId": "shape_2",
+    "text": "Title",
+    "type": "insertText",
+  },
+  {
+    "objectId": "shape_2",
+    "range": {
+      "end": 5,
+      "start": 0,
+    },
+    "style": {
+      "fontFamily": "Geist",
+      "fontSize": 56,
+      "foregroundColor": "#0b0b0b",
+    },
+    "type": "updateTextStyle",
+  },
+  {
+    "objectId": "shape_2",
+    "range": {
+      "end": 5,
+      "start": 0,
+    },
+    "style": {
+      "alignment": "START",
+      "lineSpacing": 1.1,
+    },
+    "type": "updateParagraphStyle",
+  },
+]
+`;
+
+exports[`renderToOps — Image primitive > emits createSlide → createImage with the resolved URL and rect > ops 1`] = `
+[
+  {
+    "insertAt": 0,
+    "slideId": "slide_1",
+    "type": "createSlide",
+  },
+  {
+    "imageId": "image_2",
+    "rect": {
+      "h": 6858000,
+      "w": 12192000,
+      "x": 0,
+      "y": 0,
+    },
+    "slideId": "slide_1",
+    "type": "createImage",
+    "url": "https://cdn.example.com/hero.png",
+  },
+]
+`;
+
+exports[`renderToOps — function components compose > a function component returning <Slide> resolves correctly > ops 1`] = `
+[
+  {
+    "insertAt": 0,
+    "slideId": "slide_1",
+    "type": "createSlide",
+  },
+  {
+    "rect": {
+      "h": 1270000,
+      "w": 7620000,
+      "x": 685800,
+      "y": 685800,
+    },
+    "shape": "TEXT_BOX",
+    "shapeId": "shape_2",
+    "slideId": "slide_1",
+    "type": "createShape",
+  },
+  {
+    "objectId": "shape_2",
+    "text": "Hello",
+    "type": "insertText",
+  },
+  {
+    "objectId": "shape_2",
+    "range": {
+      "end": 5,
+      "start": 0,
+    },
+    "style": {
+      "bold": true,
+    },
+    "type": "updateTextStyle",
+  },
+]
+`;
+
+exports[`renderToOps — multi-slide deck > emits ops for each slide in document order with stable IDs > ops 1`] = `
+[
+  {
+    "insertAt": 0,
+    "slideId": "slide_1",
+    "type": "createSlide",
+  },
+  {
+    "rect": {
+      "h": 635000,
+      "w": 1270000,
+      "x": 0,
+      "y": 0,
+    },
+    "shape": "TEXT_BOX",
+    "shapeId": "shape_2",
+    "slideId": "slide_1",
+    "type": "createShape",
+  },
+  {
+    "objectId": "shape_2",
+    "text": "A",
+    "type": "insertText",
+  },
+  {
+    "insertAt": 1,
+    "slideId": "slide_3",
+    "type": "createSlide",
+  },
+  {
+    "rect": {
+      "h": 635000,
+      "w": 1270000,
+      "x": 0,
+      "y": 0,
+    },
+    "shape": "TEXT_BOX",
+    "shapeId": "shape_4",
+    "slideId": "slide_3",
+    "type": "createShape",
+  },
+  {
+    "objectId": "shape_4",
+    "text": "B",
+    "type": "insertText",
+  },
+]
+`;
+
+exports[`renderToOps — multiple text runs in one Box > concatenates text and emits per-run style spans for non-empty styles > ops 1`] = `
+[
+  {
+    "insertAt": 0,
+    "slideId": "slide_1",
+    "type": "createSlide",
+  },
+  {
+    "rect": {
+      "h": 1270000,
+      "w": 7620000,
+      "x": 685800,
+      "y": 685800,
+    },
+    "shape": "TEXT_BOX",
+    "shapeId": "shape_2",
+    "slideId": "slide_1",
+    "type": "createShape",
+  },
+  {
+    "objectId": "shape_2",
+    "text": "Bold middle orange",
+    "type": "insertText",
+  },
+  {
+    "objectId": "shape_2",
+    "range": {
+      "end": 5,
+      "start": 0,
+    },
+    "style": {
+      "bold": true,
+    },
+    "type": "updateTextStyle",
+  },
+  {
+    "objectId": "shape_2",
+    "range": {
+      "end": 18,
+      "start": 12,
+    },
+    "style": {
+      "foregroundColor": "#ff5500",
+    },
+    "type": "updateTextStyle",
+  },
+]
+`;
+
+exports[`renderToOps — single slide with one box > emits createSlide → createShape → insertText in order > manifest 1`] = `
+{
+  "artifacts": [],
+  "deckId": null,
+  "generatedAt": "2026-05-04T15:00:00.000Z",
+  "generatedBy": "react-pptx",
+  "manifestVersion": "1",
+  "slots": {},
+  "templateName": "test",
+}
+`;
+
+exports[`renderToOps — single slide with one box > emits createSlide → createShape → insertText in order > ops 1`] = `
+[
+  {
+    "insertAt": 0,
+    "slideId": "slide_1",
+    "type": "createSlide",
+  },
+  {
+    "rect": {
+      "h": 1270000,
+      "w": 7620000,
+      "x": 685800,
+      "y": 685800,
+    },
+    "shape": "TEXT_BOX",
+    "shapeId": "shape_2",
+    "slideId": "slide_1",
+    "type": "createShape",
+  },
+  {
+    "objectId": "shape_2",
+    "text": "Hello, world.",
+    "type": "insertText",
+  },
+]
+`;
+
+exports[`renderToOps — slotId attaches the shape to the manifest > records SlotId → shapeId for each slot-bearing Box > slot map 1`] = `
+{
+  "cover:subtitle": "shape_3",
+  "cover:title": "shape_2",
+}
+`;

package/src/core/components.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from 'vitest';
+import { Box, Color, Text, Image, isPrimitive, PRIMITIVES, Slide } from './components.js';
+
+const TEST_ARTIFACT = {
+  type: 'image',
+  identifier: 'test-image',
+  resolvedUrl: 'https://example.com/x.png',
+  resolvedAt: '2026-05-04T15:00:00.000Z',
+} as const;
+
+describe('primitives', () => {
+  test('each primitive has a stable __rgsKind tag', () => {
+    expect(Slide.__rgsKind).toBe('Slide');
+    expect(Box.__rgsKind).toBe('Box');
+    expect(Text.__rgsKind).toBe('Text');
+    expect(Color.__rgsKind).toBe('Color');
+    expect(Image.__rgsKind).toBe('Image');
+  });
+
+  test('primitives render to null (inert under react-dom)', () => {
+    // Calling them as plain functions; the reconciler never does this directly,
+    // but accidental react-dom rendering must not blow up.
+    expect(Slide({})).toBeNull();
+    expect(Box({ rect: { x: 0, y: 0, w: 1, h: 1 } })).toBeNull();
+    expect(Text({})).toBeNull();
+    expect(Color({ color: '#ffffff' })).toBeNull();
+    expect(
+      Image({
+        rect: { x: 0, y: 0, w: 1, h: 1 },
+        image: { url: TEST_ARTIFACT.resolvedUrl, artifact: TEST_ARTIFACT },
+      }),
+    ).toBeNull();
+  });
+
+  test('PRIMITIVES contains exactly the five host elements', () => {
+    expect(Object.keys(PRIMITIVES).sort()).toEqual(['Box', 'Color', 'Image', 'Slide', 'Text']);
+  });
+});
+
+describe('isPrimitive', () => {
+  test('returns true for each primitive component', () => {
+    expect(isPrimitive(Slide)).toBe(true);
+    expect(isPrimitive(Box)).toBe(true);
+    expect(isPrimitive(Text)).toBe(true);
+    expect(isPrimitive(Color)).toBe(true);
+    expect(isPrimitive(Image)).toBe(true);
+  });
+
+  test('returns false for arbitrary functions and primitives', () => {
+    const NotMine = () => null;
+    expect(isPrimitive(NotMine)).toBe(false);
+    expect(isPrimitive('div')).toBe(false);
+    expect(isPrimitive(undefined)).toBe(false);
+    expect(isPrimitive(null)).toBe(false);
+    expect(isPrimitive(42)).toBe(false);
+  });
+});

package/src/core/components.ts

@@ -0,0 +1,196 @@
+/**
+ * The minimal JSX primitive surface the reconciler walks.
+ *
+ * **This is intentionally a small, lower-case set.** High-level brand
+ * components (`<Cover/>`, `<TwoColumn/>`, etc.) live in brand packages
+ * (e.g., `@sanity-labs/slides`) and *compose* these primitives. The substrate
+ * exports just enough to render an arbitrary slide tree.
+ *
+ * Why hand-rolled host elements rather than `<div>`-style intrinsic elements:
+ * we want the reconciler to recognize these by *type identity*, not by string
+ * tag names. Type identity removes a class of bugs ("did you mean 'box' or
+ * 'Box'?") and gives the type-checker something concrete to enforce.
+ *
+ * These don't render to the DOM — they're inert markers the reconciler walks.
+ * They return `null` so they're harmless if accidentally rendered through
+ * react-dom (e.g., during Storybook prototyping).
+ */
+
+import type { ReactNode } from 'react';
+import type { Rect } from './geometry.js';
+import type { ArtifactRef, SlotId } from './manifest.js';
+import type { HexColor, ParagraphStyle, TextStyle } from './runtime.js';
+
+/**
+ * A single slide in the deck.
+ *
+ * Every `<Slide>` becomes a `createSlide` op. Children are rendered into the
+ * slide's coordinate space.
+ */
+export interface SlideProps {
+  /** Children: `<Box>` and `<Image>` shapes laid out inside the slide. */
+  children?: ReactNode;
+}
+
+/**
+ * A discriminated union describing a `<Box>`'s background fill.
+ *
+ * Shaped as a tagged union — *not* a flat `fill?: HexColor` — so future fill
+ * kinds (texture, image-as-background, gradient) can be added without
+ * sprouting parallel optional props. The discriminator is load-bearing:
+ * off-brand fills are inexpressible at the type level when a brand component
+ * narrows what kinds it accepts.
+ *
+ * Today only `'solid'` is supported. Image fills (full-bleed photos) are
+ * authored as `<Image>` siblings of `<Box>` rather than nested inside a
+ * Box's fill.
+ */
+export type BoxFill = { kind: 'solid'; color: HexColor };
+
+/**
+ * A rectangular text box on the slide canvas.
+ *
+ * Becomes a `createShape` op with shape `TEXT_BOX` (the only shape this
+ * primitive set produces; other shape kinds are reserved for the future).
+ * Children are concatenated into a single text run with style spans.
+ */
+export interface BoxProps {
+  /** The shape's rect in *points*. The reconciler converts to EMU at the boundary. */
+  rect: Rect;
+
+  /**
+   * Optional slot ID, encoded into the shape's alt-text. Required for any text
+   * box that re-fill should target. Format: `<componentName>:<slotName>`,
+   * e.g., `"cover:title"`. See `manifest.ts` for encoding details.
+   */
+  slotId?: SlotId;
+
+  /**
+   * Optional background fill. When set, the reconciler emits an
+   * `updateShapeProperties` op immediately after the shape is created,
+   * before any text or text-style ops. An empty Box (no children) with a
+   * `fill` is a valid full-bleed colored background.
+   */
+  fill?: BoxFill;
+
+  /** Default text style applied to the shape's contents. */
+  textStyle?: TextStyle;
+
+  /** Default paragraph style. */
+  paragraphStyle?: ParagraphStyle;
+
+  /** Children: `<Text>` runs and/or raw strings. */
+  children?: ReactNode;
+}
+
+/**
+ * A styled text run inside a `<Box>`.
+ *
+ * Multiple `<Text>` children of the same `<Box>` are concatenated; each
+ * run's style is applied to its character range via `updateTextStyle` ops.
+ * Raw string children of `<Box>` are equivalent to `<Text>{text}</Text>`
+ * with no style override.
+ *
+ * The intent of carrying `textStyle` here (rather than mandating a typography
+ * token) is: high-level brand components compose this primitive *and* enforce
+ * brand-token discipline at *their* layer. The substrate stays brand-agnostic.
+ */
+export interface TextProps {
+  /** Style applied to this run only. Merges over `<Box>`'s `textStyle`. */
+  textStyle?: TextStyle;
+  /** Children: text content. Nested elements are flattened to their text. */
+  children?: ReactNode;
+}
+
+/**
+ * A wrapper that sets the foreground color of its children.
+ *
+ * A thin convenience over `<Text textStyle={{foregroundColor}}/>` so
+ * brand components can read more declaratively. The reconciler treats this
+ * identically to a `<Text>` with the same style.
+ */
+export interface ColorProps {
+  /** The color to apply, as a 24-bit hex. (`#RRGGBB`.) */
+  color: HexColor;
+  /** Children: text or `<Text>` runs. */
+  children?: ReactNode;
+}
+
+/**
+ * A reference to a brand-resolved image, including its provenance.
+ *
+ * The `artifact` field is **required**: every image rendered through the
+ * substrate is recorded in the generation manifest's `artifacts` list, so
+ * downstream tooling can detect 404s and verify content integrity. An
+ * `<Image>` without a `ArtifactRef` is impossible to construct —
+ * type-level enforcement of the manifest contract.
+ */
+export interface ImageRef {
+  /** Resolved URL the runtime will fetch the image bytes from. */
+  readonly url: string;
+  /** Template-artifact provenance — recorded in manifest.artifacts. Required. */
+  readonly artifact: ArtifactRef;
+}
+
+/**
+ * A bitmap image placed on a slide, rendered as a `createImage` op.
+ *
+ * Sibling of `<Box>` inside a `<Slide>`. Used for full-bleed background
+ * photos, dot-grid texture overlays, brand logos, and any other rasterized
+ * brand artifact. Vector content (lines, rectangles, etc.) goes through
+ * `<Box>` and the (future) shape-kind extension to its fill prop.
+ */
+export interface ImageProps {
+  /** The image's rect in *points*. The reconciler converts to EMU at the boundary. */
+  rect: Rect;
+
+  /**
+   * The image to render, including its brand-artifact provenance. Required —
+   * an `<Image>` without an `ImageRef` is unconstructable, by design.
+   */
+  image: ImageRef;
+
+  /**
+   * Optional slot ID. When set, the reconciler records `SlotId → imageId` in
+   * the manifest's slot registry.
+   */
+  slotId?: SlotId;
+
+  /**
+   * Accessibility alt-text shown to assistive tech.
+   *
+   * Carried through to the `createImage` op's `altText` field.
+   */
+  altText?: string;
+}
+
+/** A unique brand for each primitive's React component. */
+type Marker<TProps> = ((props: TProps) => null) & { readonly __rgsKind: string };
+
+const makeMarker = <TProps>(kind: string): Marker<TProps> => {
+  const component = (_props: TProps): null => null;
+  // Display name aids debugging in React DevTools and assertion messages.
+  Object.defineProperty(component, 'name', { value: kind });
+  return Object.assign(component, { __rgsKind: kind } as const);
+};
+
+export const Slide = makeMarker<SlideProps>('Slide');
+export const Box = makeMarker<BoxProps>('Box');
+export const Text = makeMarker<TextProps>('Text');
+export const Color = makeMarker<ColorProps>('Color');
+export const Image = makeMarker<ImageProps>('Image');
+
+/**
+ * The set of primitive React components the reconciler recognizes.
+ *
+ * Used internally for type identity checks (see `reconciler.ts`). Exposed for
+ * downstream packages that want to detect "is this a substrate primitive?"
+ * without importing each one individually.
+ */
+export const PRIMITIVES = { Slide, Box, Text, Color, Image } as const;
+
+const PRIMITIVE_SET = new Set<unknown>(Object.values(PRIMITIVES));
+
+/** Type guard: is this React element type one of our primitives? */
+export const isPrimitive = (type: unknown): type is (typeof PRIMITIVES)[keyof typeof PRIMITIVES] =>
+  PRIMITIVE_SET.has(type);