feat: attribute standardization (#1685)

The current attributes for our standard annotations have some messiness about them. This is an effort to clean up attributes and to provide a more standardized API that is consistent across more annotations. These decisions are made in conjunction with thinking about how our content is presented by our designers for sites like vogue.com, where some features that editors and writers use are not representable currently in our annotations.

We would like to provide more support and therefore, I'm introducing two major changes:

size and inset become layout.
These fields did not mix and match and allowing both properties made it confusing for developers as to which field took precedence. This also allows designers to add new types of layouts without having to change the data model.
alignment becomes textAlignment
This is pretty self-explanatory, and is about clarity.
Note that layout as a property is added to many more blocks than size and inset were on previously. This is intentional, since there are instances where editorial teams have used these features on these blocks. We may not provide them controls to change these properties, but we would like to fully support these and respect their decisions when it comes time to represent the data for our sites to use for rendering.

Additionally, support was added for x.com / twitter.com, and other unimplemented embeds were removed.

packages/@atjson/offset-annotations/src/annotations/blockquote.ts

@@ -1,7 +1,18 @@
 import { BlockAnnotation } from "@atjson/document";
+import { TextAlignment } from "../utils/enums";
 
 export class Blockquote extends BlockAnnotation<{
-  inset?: "left" | "right";
+  /**
+   * Layout information, used to indicate mutually
+   * exclusive layouts, for example sizes, floats, etc.
+   */
+  layout?: string;
+
+  /**
+   * Text alignment of the block.
+   */
+  textAlignment?: TextAlignment;
+
   /**
    * A named identifier used to quickly jump to this item
    */

packages/@atjson/offset-annotations/src/annotations/ceros-embed.ts

@@ -1,10 +1,30 @@
 import { BlockAnnotation } from "@atjson/document";
 
 export class CerosEmbed extends BlockAnnotation<{
+  /**
+   * The URL to the Ceros experience.
+   */
   url: string;
+
+  /**
+   * The aspect ratio, as a fraction of the embed, which
+   * is used so the embed can be scaled automatically
+   * by the Ceros script tag.
+   */
   aspectRatio: number;
+
+  /**
+   * The mobile aspect ratio of the embed, which is chosen
+   * by Ceros when on smaller screen sizes.
+   */
   mobileAspectRatio?: number;
-  size?: "small" | "medium" | "large";
+
+  /**
+   * Layout information, used to indicate mutually
+   * exclusive layouts, for example sizes, floats, etc.
+   */
+  layout?: string;
+
   /**
    * A named identifier used to quickly jump to this item
    */

packages/@atjson/offset-annotations/src/annotations/cne-audio-embed.ts

@@ -6,9 +6,31 @@ export enum AudioEnvironments {
 }
 
 export class CneAudioEmbed extends BlockAnnotation<{
+  /**
+   * Indicates the environment that the audio was published in.
+   */
   audioEnv: AudioEnvironments;
+
+  /**
+   * The type of audio embed.
+   */
   audioType: string;
+
+  /**
+   * The unique id of the audio, used to embed the
+   * podcast / episode / etc.
+   */
   audioId: string;
+
+  /**
+   * Layout information, used to indicate mutually
+   * exclusive layouts, for example sizes, floats, etc.
+   */
+  layout?: string;
+
+  /**
+   * A named identifier used to quickly jump to this item
+   */
   anchorName?: string;
 }> {
   static vendorPrefix = "offset";

packages/@atjson/offset-annotations/src/annotations/facebook-embed.ts

@@ -1,6 +1,33 @@
-import { IframeEmbed } from "./iframe-embed";
+import { BlockAnnotation } from "@atjson/document";
 
-export class FacebookEmbed extends IframeEmbed {
+export class FacebookEmbed extends BlockAnnotation<{
+  /**
+   * The URL to the embed on www.facebook.com
+   */
+  url: string;
+
+  /**
+   * If set to true, this hides the text attached to a photo post.
+   */
+  hideText?: boolean;
+
+  /**
+   * Layout information, used to indicate mutually
+   * exclusive layouts, for example sizes, floats, etc.
+   */
+  layout?: string;
+
+  /**
+   * A named identifier used to quickly jump to this item
+   */
+  anchorName?: string;
+
+  /**
+   * The post content at the time of embedding, ususally
+   * a textual representation of the content with some links.
+   */
+  content?: string;
+}> {
   static type = "facebook-embed";
   static vendorPrefix = "offset";
 }

packages/@atjson/offset-annotations/src/annotations/firework-embed.ts

@@ -1,9 +1,28 @@
 import { BlockAnnotation } from "@atjson/document";
 
 export class FireworkEmbed extends BlockAnnotation<{
+  /**
+   * The id of the Firework video playlist.
+   */
   playlistId: string;
+
+  /**
+   * The channel used to track Firework video embeds.
+   */
   channel?: string;
+
+  /**
+   * Deterimines how the video should open when they
+   * are clicked.
+   */
   open?: "default" | "_self" | "_modal" | "_blank";
+
+  /**
+   * Layout information, used to indicate mutually
+   * exclusive layouts, for example sizes, floats, etc.
+   */
+  layout?: string;
+
   /**
    * A named identifier used to quickly jump to this item
    */

packages/@atjson/offset-annotations/src/annotations/group.ts

@@ -18,7 +18,19 @@ import { BlockAnnotation } from "@atjson/document";
  */
 export class Group<T = {}> extends BlockAnnotation<
   T & {
+    /**
+     * Art direction information about how the group should
+     * be laid out. Properties here can determine whether
+     * media should be shown as a diptych, masonry, stacked, etc.
+     */
     artDirection: string;
+
+    /**
+     * Layout information, used to indicate mutually
+     * exclusive layouts, for example sizes, floats, etc.
+     */
+    layout?: string;
+
     /**
      * A named identifier used to quickly jump to this item
      */

packages/@atjson/offset-annotations/src/annotations/heading.ts

@@ -1,8 +1,25 @@
 import { BlockAnnotation } from "@atjson/document";
+import { TextAlignment } from "../utils/enums";
 
 export class Heading extends BlockAnnotation<{
+  /**
+   * The heading level, from 1-6 as mapped to from
+   * DOM headings. These should correspond with
+   * accessiblity levels.
+   */
   level: 1 | 2 | 3 | 4 | 5 | 6;
-  alignment?: "start" | "center" | "end" | "justify";
+
+  /**
+   * Layout information, used to indicate mutually
+   * exclusive layouts, for example sizes, floats, etc.
+   */
+  layout?: string;
+
+  /**
+   * Text alignment of the block.
+   */
+  textAlignment?: TextAlignment;
+
   /**
    * A named identifier used to quickly jump to this item
    */

packages/@atjson/offset-annotations/src/annotations/horizontal-rule.ts

@@ -1,6 +1,13 @@
 import { BlockAnnotation } from "@atjson/document";
 
-export class HorizontalRule extends BlockAnnotation {
+export class HorizontalRule extends BlockAnnotation<{
+  /**
+   * Indicates a stylistic alternate for a horizontal
+   * rule, which can be used to divide content for
+   * special reports or stories.
+   */
+  style?: string;
+}> {
   static vendorPrefix = "offset";
   static type = "horizontal-rule";
 }

packages/@atjson/offset-annotations/src/annotations/iframe-embed.ts

@@ -1,15 +1,43 @@
 import { BlockAnnotation } from "@atjson/document";
 
 export class IframeEmbed extends BlockAnnotation<{
+  /**
+   * The embed URL to host in the iframe.
+   */
   url: string;
+
+  /**
+   * The width of the embed, as a valid CSS unit
+   * (rem, em, pixels, percentages).
+   */
   width?: string;
+
+  /**
+   * The height of the embed, as a valid CSS unit
+   * (rem, em, pixels, percentages).
+   */
   height?: string;
+
   /**
-   * Refers to a slice instead of being an
-   * embedded document.
+   * Refers to a slice instead of being an embedded document.
    */
   caption?: string;
+
+  /**
+   * Layout information, used to indicate mutually
+   * exclusive layouts, for example sizes, floats, etc.
+   *
+   * For iframe embeds, this may be used to flex an iframe
+   * with sizing using percentages.
+   */
+  layout?: string;
+
+  /**
+   * Sandbox properties that indicate what permissions are required
+   * by the embedded context so it can run correctly.
+   */
   sandbox?: string;
+
   /**
    * A named identifier used to quickly jump to this item
    */

packages/@atjson/offset-annotations/src/annotations/image.ts

@@ -1,9 +1,25 @@
 import { ObjectAnnotation } from "@atjson/document";
 
 export class Image extends ObjectAnnotation<{
+  /**
+   * The URL to the image.
+   */
   url: string;
+
+  /**
+   * The title of the image, provided for compatibility
+   * with markdown and HTML.
+   */
   title?: string;
+
+  /**
+   * A description of the image, used for assistive
+   * technology to provide information to someone
+   * that may need help describing the contents of
+   * the image.
+   */
   description?: string;
+
   /**
    * A named identifier used to quickly jump to this item
    */

packages/@atjson/offset-annotations/src/annotations/index.ts

@@ -1,6 +1,5 @@
 export * from "./blockquote";
 export * from "./bold";
-export * from "./caption-source";
 export * from "./ceros-embed";
 export * from "./cne-audio-embed";
 export * from "./cne-event-registration-embed";
@@ -34,7 +33,6 @@ export * from "./strikethrough";
 export * from "./subscript";
 export * from "./superscript";
 export * from "./table";
-export * from "./telegram-embed";
 export * from "./tiktok-embed";
 export * from "./twitter-embed";
 export * from "./underline";

packages/@atjson/offset-annotations/src/annotations/instagram-embed.ts

@@ -1,6 +1,34 @@
-import { IframeEmbed } from "./iframe-embed";
+import { BlockAnnotation } from "@atjson/document";
 
-export class InstagramEmbed extends IframeEmbed {
+export class InstagramEmbed extends BlockAnnotation<{
+  /**
+   * The URL to the post on www.instagram.com
+   */
+  url: string;
+
+  /**
+   * If set to false, this excludes the caption attached to the post.
+   * This maps to the `captioned` option on the embed.
+   */
+  excludePostCaption?: boolean;
+
+  /**
+   * Layout information, used to indicate mutually
+   * exclusive layouts, for example sizes, floats, etc.
+   */
+  layout?: string;
+
+  /**
+   * A named identifier used to quickly jump to this item
+   */
+  anchorName?: string;
+
+  /**
+   * The post content at the time of embedding, ususally
+   * a textual representation of the content with some links.
+   */
+  content?: string;
+}> {
   static type = "instagram-embed";
   static vendorPrefix = "offset";
 }