* Remove deprecated and unsupported interfaces

* Add new interfaces and previously missed interfaces
* Update URI validation method, wraps around native URL class and references supported extensions list
* Add changelog

CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## v0.3.0 - December 4, 2021
+
+This should bring the individual components more or less up to date, but what's lacking is a more thorough audit to be certain.
+
+Some components may still not be exposed at the root level except through the global namespace `Component`.
+
+#### Changes:
+* Globally exposed component renamed `Facebook` -> `FacebookPost` to match Apple's spec
+* Updated URI validation method. Now wraps around native URL class and checks against a list of valid file extensions - these may need updating. Couldn't find a canonical list of all valid file types
+* Added `ColorSchema` interface.
+* Removed unsupported advertisement classes: `MediumRectangleAdvertisement` and `BannerAdvertisment`
+* Add missing fields to several A/V components
+* Other minor housecleaning changes

README.md

@@ -2,6 +2,8 @@
 
 [![CircleCI](https://circleci.com/gh/Robert-Fairley/apple-news-format.svg?style=svg&circle-token=6f3e22cb14ceb409d7241efc628ccdef34b810f8)](https://circleci.com/gh/Robert-Fairley/apple-news-format)
 
+**Current to ANF version: `1.17.0`**
+
 This is a collection of TypeScript types for the Apple News Format fields, metadata, and components.
 
 Included are a small selection of validation functions for certain fields that contain restrictions on the strings that are passed in.

package.json

@@ -40,6 +40,7 @@
   "devDependencies": {
     "@types/chai": "^4.1.7",
     "@types/mocha": "^5.2.6",
+    "@types/node": "^16.11.11",
     "chai": "^4.2.0",
     "husky": "^1.3.1",
     "mocha": "^9.1.3",

src/apple-news.d.ts

@@ -36,8 +36,7 @@ declare namespace AppleNews {
   export type ComponentLink = Components.ComponentLink;
   export type Component = Components.Component;
   export type Scene = Components.Scene;
-  export type BannerAdvertisement = Components.Advertisements.BannerAdvertisement;
-  export type MediumRectangleAdvertisement = Components.Advertisements.MediumRectangleAdvertisement;
+  export type ReplicaAdvertisement = Components.Advertisements.ReplicaAdvertisement;
   export type ArticleLink = Components.ArticleStructure.ArticleLink;
   export type Aside = Components.ArticleStructure.Aside;
   export type Chapter = Components.ArticleStructure.Chapter;
@@ -67,9 +66,10 @@ declare namespace AppleNews {
   export type MapSpan = Components.Location.MapSpan;
   export type Map = Components.Location.Map;
   export type Place = Components.Location.Place;
-  export type Instagram = Components.SocialMedia.SocialMediaComponent;
-  export type Facebook = Components.SocialMedia.SocialMediaComponent;
-  export type Tweet = Components.SocialMedia.SocialMediaComponent;
+  export type Instagram = Components.SocialMedia.Instagram;
+  export type FacebookPost = Components.SocialMedia.FacebookPost;
+  export type TikTok = Components.SocialMedia.TikTok;
+  export type Tweet = Components.SocialMedia.Tweet;
   export type DataDescriptor = Components.Tables.DataDescriptor;
   export type DataFormat = Components.Tables.DataFormat;
   export type DataTableSorting = Components.Tables.DataTableSorting;

src/article-document.ts

@@ -7,13 +7,16 @@ import { AnyComponent } from "./components/any-component";
 import { DocumentStyle } from "./document-style";
 import { Metadata } from "./metadata";
 import { ComponentStyles } from "./styles/component-styles";
+import { ColorScheme } from "./color-scheme";
 import {
     ComponentTextStyles,
     TextStyles,
 } from "./styles/text-styles";
+import { TextFormat } from "./primitives/text";
 
 /**
  * Signature/interface for the `ArticleDocument` object
+ * @see https://developer.apple.com/documentation/apple_news/articledocument
  */
 export interface ArticleDocument {
     components: AnyComponent[];
@@ -24,10 +27,11 @@ export interface ArticleDocument {
     title: string;
     version: string;
     autoplacement?: AutoPlacement;
+    colorScheme?: ColorScheme;
     componentLayouts?: ComponentLayouts;
     componentStyles?: ComponentStyles;
     documentStyle?: DocumentStyle;
     metadata?: Metadata;
-    subtitle?: string;
+    textFormat?: TextFormat;
     textStyles?: TextStyles;
 }

src/article-layout/component-layout-base.ts

@@ -20,82 +20,16 @@ export type IgnoreDocumentParameters
  * @see https://developer.apple.com/documentation/apple_news/componentlayout
  */
 export interface ComponentLayoutBase {
-    /**
-     * A number that indicates how many columns the component spans, based on the number of columns in the document.
-     * Minimum: 1
-     * @type Unsigned Integer
-     */
     columnSpan?: number; // Unisigned Integer - minimum 1
-    /**
-     * A number that indicates which column the component‘s start position is in,
-     * based on the number of columns in the document or parent container.
-     * Minimum: 0
-     * @type Unsigned Integer
-     */
     columnStart?: number; // Unsigned Integer
-    /**
-     * A string value that sets the alignment of the content within the component.
-     * This property applies only when the width of the content is less than the width of the component.
-     * @type boolean | HorizontalAlignment
-     */
     horizontalContentAlignment?: HorizontalAlignment;
-    /**
-     * A value that indicates whether the gutters (if any) to the left and right of the component should be ignored.
-     * The gutter size is defined in the Layout object at the root level of the document.
-     * @type boolean | IgnoreDocumentParameters
-     */
     ignoreDocumentGutter?: boolean | IgnoreDocumentParameters;
-    /**
-     * A value that indicates whether the component should respect or ignore the document’s margins.
-     * Ignoring document margins positions the component based on the document's width and margin.
-     * @type boolean | IgnoreDocumentParameters
-     */
     ignoreDocumentMargin?: boolean | IgnoreDocumentParameters;
-    /**
-     * A value that indicates whether the component should respect or ignore the viewport padding.
-     * Ignoring viewport padding positions the component at the edge of the display screen.
-     * This property affects the layout only if the component is in the first or last column.
-     * @type boolean | IgnoreDocumentParameters
-     */
     ignoreViewportPadding?: boolean | IgnoreDocumentParameters;
-    /**
-     * A value that sets the margins for the top and bottom of the component, as a single integer
-     * that gets applied to the top and bottom margins, or as an object containing separate properties for top and bottom.
-     * @type Margin | Integer
-     */
     margin?: Margin | number; // Integer
-    /**
-     * A value that sets the maximum width of the content within the component.
-     * Specify this value as a number in points or using one of the available units of measure for components.
-     * @type SupportedUnits | Integer
-     */
     maximumContentWidth?: SupportedUnits | number;
-    /**
-     * A value that sets the minimum height of the component. A component is taller than its
-     * defined minimumHeight when the contents require the component to be taller.
-     * The minimum height can be defined as a number in points or using one of the
-     * available units of measure for components.
-     * @type SupportedUnits | Integer
-     */
     minimumHeight?: SupportedUnits | number;
-    /**
-     * A value that defines the minimum width of the layout when used within a Container
-     * with HorizontalStackDisplay as the specified contentDisplay type. The minimum width
-     * can be defined as a number in points or using one of the available units of measure for components.
-     * @type SupportedUnits | Integer
-     */
     minimumWidth?: SupportedUnits | number;
-    /**
-     * A value that defines the maximum width of the layout when used within a Container
-     * with HorizontalStackDisplay as the specified contentDisplay type. The maximum width can be
-     * defined as a number in points or using one of the available units of measure for components.
-     * @type SupportedUnits | Integer
-     */
     maximumWidth?: SupportedUnits | number;
-    /**
-     * A value that defines the padding between the content of the component and the edges of the component.
-     * Padding can be defined as a number in points or using one of the available units of measure for components.
-     * @type SupportedUnits | Padding | Integer
-     */
     padding?: SupportedUnits | Padding | number;
 }

src/article-layout/layout.ts

@@ -5,6 +5,6 @@
 export interface Layout {
     columns: number; // Integer - Minimum: 1
     width: number; // Integer - Minimum 1
-    gutter?: number; // Unsigned Integer
-    margin?: number; // Unsigned Integer
+    gutter?: number; // Integer
+    margin?: number; // Integer
 }

src/color-scheme.ts

@@ -0,0 +1,7 @@
+/**
+ * Object containing information about document color scheme and dark mode.
+ * @see https://developer.apple.com/documentation/apple_news/articledocument/colorscheme
+ */
+export interface ColorScheme {
+    automaticDarkModeEnabled?: boolean;    
+}

src/components/advertisements/index.ts

@@ -1,2 +1 @@
-export { BannerAdvertisement } from "./banner-advertisement";
-export { MediumRectangleAdvertisement } from "./medium-rectangle-advertisement";
+export { ReplicaAdvertisement } from "./replica-advertisement";

src/components/advertisements/replica-advertisement.ts

@@ -0,0 +1,11 @@
+import { Component, ComponentLink } from "..";
+import { URI } from "../../primitives";
+
+export interface ReplicaAdvertisement extends Component {
+    role: "replica_advertisement";
+    URL: URI;
+    accessibilityCaption?: string;
+    additions?: ComponentLink[];
+    caption?: string;
+    explicitContent?: boolean;
+}

src/components/any-component.ts

@@ -1,7 +1,8 @@
 import * as Components from ".";
 
-export type AnyComponent = Components.Advertisements.BannerAdvertisement
- | Components.Advertisements.MediumRectangleAdvertisement
+export type AnyComponent
+ = Components.Addition
+ | Components.Advertisements.ReplicaAdvertisement
  | Components.ArticleStructure.ArticleLink
  | Components.ArticleStructure.Aside
  | Components.ArticleStructure.Chapter
@@ -13,6 +14,7 @@ export type AnyComponent = Components.Advertisements.BannerAdvertisement
  | Components.AudioAndVideo.EmbedWebVideo
  | Components.AudioAndVideo.Music
  | Components.AudioAndVideo.Video
+ | Components.AudioAndVideo.Podcast
  | Components.AugmentedReality.ARKit
  | Components.GalleriesAndMosaics.Gallery
  | Components.GalleriesAndMosaics.Mosaic
@@ -25,6 +27,10 @@ export type AnyComponent = Components.Advertisements.BannerAdvertisement
  | Components.Location.Map
  | Components.Location.Place
  | Components.SocialMedia.SocialMediaComponent
+ | Components.SocialMedia.FacebookPost
+ | Components.SocialMedia.Instagram
+ | Components.SocialMedia.TikTok
+ | Components.SocialMedia.Tweet
  | Components.Tables.DataTable
  | Components.Tables.HTMLTable
  | Components.Text.ArticleTitle

src/components/article-structure/article-link.ts

@@ -1,3 +1,4 @@
+import { CollectionDisplay, HorizontalStackDisplay } from ".";
 import { ContainerComponent } from "./container-component";
 
 /**
@@ -8,4 +9,6 @@ import { ContainerComponent } from "./container-component";
 export interface ArticleLink extends ContainerComponent {
   role: "article_link";
   articleIdentifier: string;
+  allowAutoplacedAds?: boolean;
+  contentDisplay?: CollectionDisplay | HorizontalStackDisplay;
 }

src/components/article-structure/index.ts

@@ -7,4 +7,5 @@ export { Container } from "./container";
 export { Divider } from "./divider";
 export { Header } from "./header";
 export { HorizontalStackDisplay } from "./horizontal-stack-display";
+export { LinkButton } from "./link-button";
 export { Section } from "./section";

src/components/article-structure/link-button.ts

@@ -0,0 +1,15 @@
+import { Component } from "..";
+import { URI } from "../../primitives";
+import { ComponentStyle } from "../../styles/component-styles";
+import { ComponentTextStyle } from "../../styles/text-styles";
+
+/**
+ * @see https://developer.apple.com/documentation/apple_news/linkbutton
+ */
+export interface LinkButton extends Component {
+    role: "link_button";
+    URL: URI;
+    accessibilityLabel?: string;
+    text?: string;
+    textStyle?: ComponentTextStyle | string;
+}

src/components/audio-and-video/audio.ts

@@ -8,5 +8,6 @@ import { AudioVideoComponent } from "./audio-video-component";
  */
 export interface Audio extends AudioVideoComponent {
   role: "audio";
+  accessibilityCaption?: string;
   imageURL?: URI;
 }

src/components/audio-and-video/embed-web-video.ts

@@ -9,5 +9,6 @@ import { AudioVideoComponent } from "./audio-video-component";
 export interface EmbedWebVideo extends AudioVideoComponent {
   role: "embedwebvideo" | "embedvideo";
   aspectRatio?: number; // Float
+  accessibilityCaption?: string;
   stillURL?: URI;
 }

src/components/audio-and-video/index.ts

@@ -1,4 +1,5 @@
 export { Audio } from "./audio";
 export { EmbedWebVideo } from "./embed-web-video";
 export { Music } from "./music";
+export { Podcast } from "./podcast";
 export { Video } from "./video";

src/components/audio-and-video/music.ts

@@ -8,5 +8,7 @@ import { AudioVideoComponent } from "./audio-video-component";
  */
 export interface Music extends AudioVideoComponent {
   role: "music";
+  accessibilityCaption?: string;
+  caption?: string;
   imageURL: URI;
 }

src/components/audio-and-video/podcast.ts

@@ -0,0 +1,15 @@
+import { AudioVideoComponent } from "./audio-video-component";
+
+export type PodcastOrientation
+    = "horizontal"
+    | "automatic";
+
+export type PodcastTheme
+    = "light"
+    | "dark"
+    | "automatic";
+
+export interface Podcast extends AudioVideoComponent {
+    orientation: PodcastOrientation;
+    theme: PodcastTheme;
+}

src/components/audio-and-video/video.ts

@@ -8,6 +8,8 @@ import { AudioVideoComponent } from "./audio-video-component";
  */
 export interface Video extends AudioVideoComponent {
   role: "video";
-  aspectRatio?: number; // Float
+  accessibilityCaption?: string;
+  aspectRatio: number; // Float
+  caption?: string;
   stillURL?: URI;
 }

src/components/social-media/facebook-post.ts

@@ -0,0 +1,8 @@
+import { SocialMediaComponent } from "./social-media-component";
+
+/**
+ * @see https://developer.apple.com/documentation/apple_news/facebookpost
+ */
+export interface FacebookPost extends SocialMediaComponent {
+    role: "facebook_post";
+}