@financial-times/content-tree 0.10.0 → 0.12.0-beta.2

package/README.md

@@ -198,6 +198,21 @@ A single semantic change to the content tree is usually split across multiple pu
 
 Before making a release you will also need to raise a pull request to increment the package.json version number, this should be made in its own PR so that at least one member of each team can approve it. Please get sign-off in the [#dynamic-storytelling-team](https://financialtimes.enterprise.slack.com/archives/C035P5DCHMH) slack channel and share this PR there.  Releases are then made via GitHub Releases: they must include a SemVer tag `vX.Y.Z` which matches the one within the package json. The release notes should be completed to communicate what changed in the release. Cutting a release will trigger CI to publish to npm for JS consumers. Go consumers can depend on the new git tag as the module version.
 
+### Beta releases
+
+If you want to make a beta release from a branch before you merge into main, you can do this with the following steps:
+
+* set your release as `v0.0.0-beta.0` where `0` is whatever version number you are setting
+* in Github, go into https://github.com/Financial-Times/content-tree/releases and press the Draft a new release button
+* when drafting the new release
+  * set the tag to the same as you have for your beta
+  * set the target to the branch that you want to release from
+  * set the Release title to the version number
+  * fill in release notes as normal
+  * check the Pre-release option under Release label
+  * Press the Publish release button
+
+
 ## License
 
 This software is published by the Financial Times under the [MIT licence](mit).

package/SPEC.md

@@ -343,28 +343,29 @@ interface Blockquote extends Parent {
 
 ```ts
 type StoryBlock =
-	| ImageSet
-	| Flourish
+	| AcastPodcast
 	| BigNumber
+	| Carousel
+	| ClipSet
 	| CustomCodeComponent
+	| Definition
+	| Flourish
+	| ImagePair
+	| ImageSet
+	| InfoBox
+	| InfoPair
+	| InNumbers
 	| Layout
 	| Pullquote
-	| ScrollyBlock
-	| ClipSet
-	| Table
 	| Recommended
 	| RecommendedList
+	| ScrollyBlock
+	| Table
+	| Timeline
 	| Tweet
 	| Video
-	| YoutubeVideo
 	| VimeoVideo
-    | AcastPodcast
-	| Timeline
-	| ImagePair
-	| InNumbers
-	| Definition
-	| InfoBox
-	| InfoPair
+	| YoutubeVideo
 ```
 
 `StoryBlock` nodes are things that can be inserted into an article body.
@@ -804,7 +805,7 @@ interface LayoutImage extends Node {
 type TableColumnSettings = {
 	hideOnMobile: boolean
 	sortable: boolean
-	sortType: 'text' | 'number' | 'date' | 'currency' | 'percent'
+	sortType?: 'text' | 'number' | 'date' | 'currency' | 'percent'
 }
 
 type TableLayoutWidth = Extract<LayoutWidth,
@@ -814,6 +815,11 @@ type TableLayoutWidth = Extract<LayoutWidth,
 		| 'inset-right'
 		| 'full-bleed'>
 
+type TableChildren =
+  | [TableCaption, TableBody, TableFooter?]
+  | [TableBody, TableFooter?]
+  | [TableCaption, TableHeader, TableBody, TableFooter?]
+  | [TableHeader, TableBody, TableFooter?]
 
 interface TableCaption extends Parent {
 	type: 'table-caption'
@@ -828,6 +834,11 @@ interface TableCell extends Parent {
 	children: Phrasing[]
 }
 
+interface TableHeader extends Parent {
+	type: 'table-header'
+	children: TableRow[]
+}
+
 interface TableRow extends Parent {
 	type: 'table-row'
 	children: TableCell[]
@@ -850,14 +861,14 @@ interface Table extends Parent {
 	layoutWidth: TableLayoutWidth
 	collapseAfterHowManyRows?: number
 	responsiveStyle: 'overflow' | 'flat' | 'scroll'
-	children: [TableCaption, TableBody, TableFooter] | [TableCaption, TableBody] | [TableBody, TableFooter] | [TableBody]
 	columnSettings: TableColumnSettings[]
+	children: TableChildren
 }
 ```
 
 **Table** represents 2d data.
 
-### CustomCodeComponent
+### `CustomCodeComponent`
 
 ```ts
 type CustomCodeComponentAttributes = {
@@ -887,7 +898,7 @@ interface CustomCodeComponent extends Node {
 - The basic interface in Spark to make reference to this system above (eg. the git repo URL or a public S3 bucket), and provide some data for it if necessary. This will be the Custom Component storyblock.
 - The data Spark receives from entering a specific ID will be used to render dynamic fields (the `attributes`).
 
-### ImagePair
+### `ImagePair`
 
 ```ts
 interface ImagePair extends Parent {
@@ -898,7 +909,7 @@ interface ImagePair extends Parent {
 
 **ImagePair** is a set of two images
 
-### Timeline
+### `Timeline`
 
 ```ts
 /**
@@ -923,7 +934,7 @@ interface TimelineEvent extends Parent {
 }
 ```
 
-### InNumbers
+### `InNumbers`
 
 ```ts
 /**
@@ -946,7 +957,7 @@ interface InNumbers extends Parent {
 }
 ```
 
-### Card
+### `Card`
 
 ```ts
 /** Allowed children for a card
@@ -963,7 +974,7 @@ interface Card extends Parent {
 }
 ```
 
-### InfoBox
+### `InfoBox`
 
 ```ts
 /**
@@ -981,7 +992,7 @@ interface InfoBox extends Parent {
 }
 ```
 
-### InfoPair
+### `InfoPair`
 
 ```ts
 /**
@@ -995,9 +1006,50 @@ interface InfoPair extends Parent {
 }
 ```
 
+### Carousels
 
+#### `CarouselCard`
+```ts
+interface CarouselCard extends Node {
+  type: "carousel-card"
+  image: ImageSet
+  title?: string
+  copy: Paragraph[]
+  additionalInfo?: string
+}
+```
+**CarouselCard** is a single item in a carousel
 
+#### `CarouselChildren`
+```ts
+/**
+ * @maxItems 10
+ * @minItems 4
+ * @sparkRepeater true
+ */
+type CarouselChildren = CarouselCard[]
+```
+**CarouselChildren** the array of carousel cards that make up a carousel
 
+#### `CarouselHeading`
+```ts
+interface CarouselHeading extends Node {
+   type: "carousel-heading"
+   title: string
+   standfirst?: string
+}
+```
+**CarouselHeading** is the main header for a carousel component
 
-
-
+#### `Carousel`
+```ts
+/**
+ * @sparkGenerateStoryBlock true
+*/
+interface Carousel extends Parent {
+   type: "carousel"
+   heading?: CarouselHeading
+   children: CarouselChildren
+}
+```
+**Carousel** is the main container for a carousel component

package/content-tree.d.ts

@@ -95,7 +95,7 @@ export declare namespace ContentTree {
         type: "blockquote";
         children: (Paragraph | Phrasing)[];
     }
-    type StoryBlock = ImageSet | Flourish | BigNumber | CustomCodeComponent | Layout | Pullquote | ScrollyBlock | ClipSet | Table | Recommended | RecommendedList | Tweet | Video | YoutubeVideo | VimeoVideo | AcastPodcast | Timeline | ImagePair | InNumbers | Definition | InfoBox | InfoPair;
+    type StoryBlock = AcastPodcast | BigNumber | Carousel | ClipSet | CustomCodeComponent | Definition | Flourish | ImagePair | ImageSet | InfoBox | InfoPair | InNumbers | Layout | Pullquote | Recommended | RecommendedList | ScrollyBlock | Table | Timeline | Tweet | Video | VimeoVideo | YoutubeVideo;
     interface Pullquote extends Node {
         type: "pullquote";
         text: string;
@@ -305,9 +305,10 @@ export declare namespace ContentTree {
     type TableColumnSettings = {
         hideOnMobile: boolean;
         sortable: boolean;
-        sortType: 'text' | 'number' | 'date' | 'currency' | 'percent';
+        sortType?: 'text' | 'number' | 'date' | 'currency' | 'percent';
     };
     type TableLayoutWidth = Extract<LayoutWidth, 'auto' | 'full-grid' | 'inset-left' | 'inset-right' | 'full-bleed'>;
+    type TableChildren = [TableCaption, TableBody, TableFooter?] | [TableBody, TableFooter?] | [TableCaption, TableHeader, TableBody, TableFooter?] | [TableHeader, TableBody, TableFooter?];
     interface TableCaption extends Parent {
         type: 'table-caption';
         children: Phrasing[];
@@ -319,6 +320,10 @@ export declare namespace ContentTree {
         rowSpan?: number;
         children: Phrasing[];
     }
+    interface TableHeader extends Parent {
+        type: 'table-header';
+        children: TableRow[];
+    }
     interface TableRow extends Parent {
         type: 'table-row';
         children: TableCell[];
@@ -338,8 +343,8 @@ export declare namespace ContentTree {
         layoutWidth: TableLayoutWidth;
         collapseAfterHowManyRows?: number;
         responsiveStyle: 'overflow' | 'flat' | 'scroll';
-        children: [TableCaption, TableBody, TableFooter] | [TableCaption, TableBody] | [TableBody, TableFooter] | [TableBody];
         columnSettings: TableColumnSettings[];
+        children: TableChildren;
     }
     type CustomCodeComponentAttributes = {
         [key: string]: string | boolean | undefined;
@@ -434,6 +439,32 @@ export declare namespace ContentTree {
         title?: string;
         children: [Card, Card];
     }
+    interface CarouselCard extends Node {
+        type: "carousel-card";
+        image: ImageSet;
+        title?: string;
+        copy: Paragraph[];
+        additionalInfo?: string;
+    }
+    /**
+     * @maxItems 10
+     * @minItems 4
+     * @sparkRepeater true
+     */
+    type CarouselChildren = CarouselCard[];
+    interface CarouselHeading extends Node {
+        type: "carousel-heading";
+        title: string;
+        standfirst?: string;
+    }
+    /**
+     * @sparkGenerateStoryBlock true
+    */
+    interface Carousel extends Parent {
+        type: "carousel";
+        heading?: CarouselHeading;
+        children: CarouselChildren;
+    }
     namespace full {
         type AssetFormat = "desktop" | "mobile" | "square" | "square-ftedit" | "standard" | "wide" | "standard-inline";
         type LayoutWidth = "auto" | "in-line" | "inset-left" | "inset-right" | "full-bleed" | "full-grid" | "mid-grid" | "full-width";
@@ -531,7 +562,7 @@ export declare namespace ContentTree {
             type: "blockquote";
             children: (Paragraph | Phrasing)[];
         }
-        type StoryBlock = ImageSet | Flourish | BigNumber | CustomCodeComponent | Layout | Pullquote | ScrollyBlock | ClipSet | Table | Recommended | RecommendedList | Tweet | Video | YoutubeVideo | VimeoVideo | AcastPodcast | Timeline | ImagePair | InNumbers | Definition | InfoBox | InfoPair;
+        type StoryBlock = AcastPodcast | BigNumber | Carousel | ClipSet | CustomCodeComponent | Definition | Flourish | ImagePair | ImageSet | InfoBox | InfoPair | InNumbers | Layout | Pullquote | Recommended | RecommendedList | ScrollyBlock | Table | Timeline | Tweet | Video | VimeoVideo | YoutubeVideo;
         interface Pullquote extends Node {
             type: "pullquote";
             text: string;
@@ -741,9 +772,10 @@ export declare namespace ContentTree {
         type TableColumnSettings = {
             hideOnMobile: boolean;
             sortable: boolean;
-            sortType: 'text' | 'number' | 'date' | 'currency' | 'percent';
+            sortType?: 'text' | 'number' | 'date' | 'currency' | 'percent';
         };
         type TableLayoutWidth = Extract<LayoutWidth, 'auto' | 'full-grid' | 'inset-left' | 'inset-right' | 'full-bleed'>;
+        type TableChildren = [TableCaption, TableBody, TableFooter?] | [TableBody, TableFooter?] | [TableCaption, TableHeader, TableBody, TableFooter?] | [TableHeader, TableBody, TableFooter?];
         interface TableCaption extends Parent {
             type: 'table-caption';
             children: Phrasing[];
@@ -755,6 +787,10 @@ export declare namespace ContentTree {
             rowSpan?: number;
             children: Phrasing[];
         }
+        interface TableHeader extends Parent {
+            type: 'table-header';
+            children: TableRow[];
+        }
         interface TableRow extends Parent {
             type: 'table-row';
             children: TableCell[];
@@ -774,8 +810,8 @@ export declare namespace ContentTree {
             layoutWidth: TableLayoutWidth;
             collapseAfterHowManyRows?: number;
             responsiveStyle: 'overflow' | 'flat' | 'scroll';
-            children: [TableCaption, TableBody, TableFooter] | [TableCaption, TableBody] | [TableBody, TableFooter] | [TableBody];
             columnSettings: TableColumnSettings[];
+            children: TableChildren;
         }
         type CustomCodeComponentAttributes = {
             [key: string]: string | boolean | undefined;
@@ -870,6 +906,32 @@ export declare namespace ContentTree {
             title?: string;
             children: [Card, Card];
         }
+        interface CarouselCard extends Node {
+            type: "carousel-card";
+            image: ImageSet;
+            title?: string;
+            copy: Paragraph[];
+            additionalInfo?: string;
+        }
+        /**
+         * @maxItems 10
+         * @minItems 4
+         * @sparkRepeater true
+         */
+        type CarouselChildren = CarouselCard[];
+        interface CarouselHeading extends Node {
+            type: "carousel-heading";
+            title: string;
+            standfirst?: string;
+        }
+        /**
+         * @sparkGenerateStoryBlock true
+        */
+        interface Carousel extends Parent {
+            type: "carousel";
+            heading?: CarouselHeading;
+            children: CarouselChildren;
+        }
     }
     namespace transit {
         type AssetFormat = "desktop" | "mobile" | "square" | "square-ftedit" | "standard" | "wide" | "standard-inline";
@@ -968,7 +1030,7 @@ export declare namespace ContentTree {
             type: "blockquote";
             children: (Paragraph | Phrasing)[];
         }
-        type StoryBlock = ImageSet | Flourish | BigNumber | CustomCodeComponent | Layout | Pullquote | ScrollyBlock | ClipSet | Table | Recommended | RecommendedList | Tweet | Video | YoutubeVideo | VimeoVideo | AcastPodcast | Timeline | ImagePair | InNumbers | Definition | InfoBox | InfoPair;
+        type StoryBlock = AcastPodcast | BigNumber | Carousel | ClipSet | CustomCodeComponent | Definition | Flourish | ImagePair | ImageSet | InfoBox | InfoPair | InNumbers | Layout | Pullquote | Recommended | RecommendedList | ScrollyBlock | Table | Timeline | Tweet | Video | VimeoVideo | YoutubeVideo;
         interface Pullquote extends Node {
             type: "pullquote";
             text: string;
@@ -1159,9 +1221,10 @@ export declare namespace ContentTree {
         type TableColumnSettings = {
             hideOnMobile: boolean;
             sortable: boolean;
-            sortType: 'text' | 'number' | 'date' | 'currency' | 'percent';
+            sortType?: 'text' | 'number' | 'date' | 'currency' | 'percent';
         };
         type TableLayoutWidth = Extract<LayoutWidth, 'auto' | 'full-grid' | 'inset-left' | 'inset-right' | 'full-bleed'>;
+        type TableChildren = [TableCaption, TableBody, TableFooter?] | [TableBody, TableFooter?] | [TableCaption, TableHeader, TableBody, TableFooter?] | [TableHeader, TableBody, TableFooter?];
         interface TableCaption extends Parent {
             type: 'table-caption';
             children: Phrasing[];
@@ -1173,6 +1236,10 @@ export declare namespace ContentTree {
             rowSpan?: number;
             children: Phrasing[];
         }
+        interface TableHeader extends Parent {
+            type: 'table-header';
+            children: TableRow[];
+        }
         interface TableRow extends Parent {
             type: 'table-row';
             children: TableCell[];
@@ -1192,8 +1259,8 @@ export declare namespace ContentTree {
             layoutWidth: TableLayoutWidth;
             collapseAfterHowManyRows?: number;
             responsiveStyle: 'overflow' | 'flat' | 'scroll';
-            children: [TableCaption, TableBody, TableFooter] | [TableCaption, TableBody] | [TableBody, TableFooter] | [TableBody];
             columnSettings: TableColumnSettings[];
+            children: TableChildren;
         }
         type CustomCodeComponentAttributes = {
             [key: string]: string | boolean | undefined;
@@ -1280,6 +1347,32 @@ export declare namespace ContentTree {
             title?: string;
             children: [Card, Card];
         }
+        interface CarouselCard extends Node {
+            type: "carousel-card";
+            image: ImageSet;
+            title?: string;
+            copy: Paragraph[];
+            additionalInfo?: string;
+        }
+        /**
+         * @maxItems 10
+         * @minItems 4
+         * @sparkRepeater true
+         */
+        type CarouselChildren = CarouselCard[];
+        interface CarouselHeading extends Node {
+            type: "carousel-heading";
+            title: string;
+            standfirst?: string;
+        }
+        /**
+         * @sparkGenerateStoryBlock true
+        */
+        interface Carousel extends Parent {
+            type: "carousel";
+            heading?: CarouselHeading;
+            children: CarouselChildren;
+        }
     }
     namespace loose {
         type AssetFormat = "desktop" | "mobile" | "square" | "square-ftedit" | "standard" | "wide" | "standard-inline";
@@ -1378,7 +1471,7 @@ export declare namespace ContentTree {
             type: "blockquote";
             children: (Paragraph | Phrasing)[];
         }
-        type StoryBlock = ImageSet | Flourish | BigNumber | CustomCodeComponent | Layout | Pullquote | ScrollyBlock | ClipSet | Table | Recommended | RecommendedList | Tweet | Video | YoutubeVideo | VimeoVideo | AcastPodcast | Timeline | ImagePair | InNumbers | Definition | InfoBox | InfoPair;
+        type StoryBlock = AcastPodcast | BigNumber | Carousel | ClipSet | CustomCodeComponent | Definition | Flourish | ImagePair | ImageSet | InfoBox | InfoPair | InNumbers | Layout | Pullquote | Recommended | RecommendedList | ScrollyBlock | Table | Timeline | Tweet | Video | VimeoVideo | YoutubeVideo;
         interface Pullquote extends Node {
             type: "pullquote";
             text: string;
@@ -1588,9 +1681,10 @@ export declare namespace ContentTree {
         type TableColumnSettings = {
             hideOnMobile: boolean;
             sortable: boolean;
-            sortType: 'text' | 'number' | 'date' | 'currency' | 'percent';
+            sortType?: 'text' | 'number' | 'date' | 'currency' | 'percent';
         };
         type TableLayoutWidth = Extract<LayoutWidth, 'auto' | 'full-grid' | 'inset-left' | 'inset-right' | 'full-bleed'>;
+        type TableChildren = [TableCaption, TableBody, TableFooter?] | [TableBody, TableFooter?] | [TableCaption, TableHeader, TableBody, TableFooter?] | [TableHeader, TableBody, TableFooter?];
         interface TableCaption extends Parent {
             type: 'table-caption';
             children: Phrasing[];
@@ -1602,6 +1696,10 @@ export declare namespace ContentTree {
             rowSpan?: number;
             children: Phrasing[];
         }
+        interface TableHeader extends Parent {
+            type: 'table-header';
+            children: TableRow[];
+        }
         interface TableRow extends Parent {
             type: 'table-row';
             children: TableCell[];
@@ -1621,8 +1719,8 @@ export declare namespace ContentTree {
             layoutWidth: TableLayoutWidth;
             collapseAfterHowManyRows?: number;
             responsiveStyle: 'overflow' | 'flat' | 'scroll';
-            children: [TableCaption, TableBody, TableFooter] | [TableCaption, TableBody] | [TableBody, TableFooter] | [TableBody];
             columnSettings: TableColumnSettings[];
+            children: TableChildren;
         }
         type CustomCodeComponentAttributes = {
             [key: string]: string | boolean | undefined;
@@ -1717,5 +1815,31 @@ export declare namespace ContentTree {
             title?: string;
             children: [Card, Card];
         }
+        interface CarouselCard extends Node {
+            type: "carousel-card";
+            image: ImageSet;
+            title?: string;
+            copy: Paragraph[];
+            additionalInfo?: string;
+        }
+        /**
+         * @maxItems 10
+         * @minItems 4
+         * @sparkRepeater true
+         */
+        type CarouselChildren = CarouselCard[];
+        interface CarouselHeading extends Node {
+            type: "carousel-heading";
+            title: string;
+            standfirst?: string;
+        }
+        /**
+         * @sparkGenerateStoryBlock true
+        */
+        interface Carousel extends Parent {
+            type: "carousel";
+            heading?: CarouselHeading;
+            children: CarouselChildren;
+        }
     }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@financial-times/content-tree",
 	"description": "content tree format",
-	"version": "0.10.0",
+	"version": "0.12.0-beta.2",
 	"publishConfig": {
 		"access": "public"
   },