@wix/editor-react-types 1.0.1 → 1.0.14

package/dist/vectorArt.d.ts

@@ -1,9 +1,34 @@
+/**
+ * A vector art (SVG) asset from Wix Media.
+ *
+ * @example
+ * ```tsx
+ * import type { VectorArt } from '@wix/editor-react-types';
+ *
+ * interface MyComponentProps {
+ *   icon?: VectorArt;
+ * }
+ * ```
+ */
 export type VectorArt = {
+    /** The SVG URI. */
     uri: string;
+    /** The SVG `viewBox` attribute value. */
     viewBox: string;
+    /** The SVG content box dimensions. */
     contentBox: string;
+    /** A map of color IDs to their resolved color values, for themeable SVGs. */
     colors: Record<string, string>;
+    /**
+     * The SVG content type, which determines how colors and theming are applied.
+     * - `'shape'` — a simple monochromatic shape.
+     * - `'color'` — a multi-color SVG.
+     * - `'tint'` — a single-color tintable SVG.
+     * - `'ugc'` — user-generated content.
+     * - `'textpath'` — text along a path.
+     */
     contentType: 'shape' | 'color' | 'tint' | 'ugc' | 'textpath';
+    /** The raw SVG markup. */
     svgContent: string;
 };
 //# sourceMappingURL=vectorArt.d.ts.map

package/dist/vectorArt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vectorArt.d.ts","sourceRoot":"","sources":["../src/vectorArt.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG;IAEpB,GAAG,EAAE,MAAM,CAAA;IAEX,OAAO,EAAE,MAAM,CAAA;IAEf,UAAU,EAAE,MAAM,CAAA;IAElB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAE9B,WAAW,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,UAAU,CAAA;IAE5D,UAAU,EAAE,MAAM,CAAA;CACrB,CAAA"}
+{"version":3,"file":"vectorArt.d.ts","sourceRoot":"","sources":["../src/vectorArt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,SAAS,GAAG;IACpB,mBAAmB;IACnB,GAAG,EAAE,MAAM,CAAA;IACX,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAA;IACf,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAA;IAClB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC9B;;;;;;;OAOG;IACH,WAAW,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,UAAU,CAAA;IAC5D,0BAA0B;IAC1B,UAAU,EAAE,MAAM,CAAA;CACrB,CAAA"}

package/dist/video.d.ts

@@ -1,26 +1,57 @@
 import type { Image } from './image';
+/** A single video file format for a given quality level. */
 export type VideoSourceType = {
+    /** The video format. */
     format: 'mp4' | 'mp4-luminance';
+    /** The video URI. */
     uri: string;
+    /** The fully resolved video URL. */
     url: string;
 };
+/** An adaptive streaming video source (HLS or DASH). */
 export type AdaptiveVideoSource = {
+    /** The adaptive streaming format. */
     format: 'hls' | 'dash';
+    /** The video URI. */
     uri: string;
+    /** The fully resolved video URL. */
     url: string;
 };
+/** A set of video files for a specific quality level. */
 export type VideoSource = {
+    /** The video quality level. */
     quality: '1080p' | '720p' | '480p' | '360p';
+    /** The video width in pixels at this quality level. */
     width: number;
+    /** The video height in pixels at this quality level. */
     height: number;
+    /** The available file types for this quality level. */
     types: Array<VideoSourceType>;
 };
+/**
+ * A video from Wix Media, including all available sources and quality levels.
+ *
+ * @example
+ * ```tsx
+ * import type { Video } from '@wix/editor-react-types';
+ *
+ * interface MyComponentProps {
+ *   video?: Video;
+ * }
+ * ```
+ */
 export type Video = {
+    /** The original video URI. */
     uri: string;
+    /** All available quality-level sources for progressive playback. */
     sources: Array<VideoSource>;
+    /** Adaptive streaming sources (HLS/DASH) for streaming playback. */
     adaptiveSources: Array<AdaptiveVideoSource>;
+    /** Whether the video contains an audio track. */
     hasAudio: boolean;
+    /** The video frame rate in frames per second. */
     fps: number;
+    /** A poster image to display before the video plays. */
     poster?: Image;
 };
 //# sourceMappingURL=video.d.ts.map

package/dist/video.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"video.d.ts","sourceRoot":"","sources":["../src/video.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAEpC,MAAM,MAAM,eAAe,GAAG;IAE1B,MAAM,EAAE,KAAK,GAAG,eAAe,CAAA;IAE/B,GAAG,EAAE,MAAM,CAAA;IAEX,GAAG,EAAE,MAAM,CAAA;CACd,CAAA;AAED,MAAM,MAAM,mBAAmB,GAAG;IAE9B,MAAM,EAAE,KAAK,GAAG,MAAM,CAAA;IAEtB,GAAG,EAAE,MAAM,CAAA;IAEX,GAAG,EAAE,MAAM,CAAA;CACd,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IAEtB,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAA;IAE3C,KAAK,EAAE,MAAM,CAAA;IAEb,MAAM,EAAE,MAAM,CAAA;IAEd,KAAK,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;CAChC,CAAA;AAED,MAAM,MAAM,KAAK,GAAG;IAChB,GAAG,EAAE,MAAM,CAAA;IAEX,OAAO,EAAE,KAAK,CAAC,WAAW,CAAC,CAAA;IAE3B,eAAe,EAAE,KAAK,CAAC,mBAAmB,CAAC,CAAA;IAE3C,QAAQ,EAAE,OAAO,CAAA;IAEjB,GAAG,EAAE,MAAM,CAAA;IAEX,MAAM,CAAC,EAAE,KAAK,CAAA;CACjB,CAAA"}
+{"version":3,"file":"video.d.ts","sourceRoot":"","sources":["../src/video.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAEpC,4DAA4D;AAC5D,MAAM,MAAM,eAAe,GAAG;IAC1B,wBAAwB;IACxB,MAAM,EAAE,KAAK,GAAG,eAAe,CAAA;IAC/B,qBAAqB;IACrB,GAAG,EAAE,MAAM,CAAA;IACX,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAA;CACd,CAAA;AAED,wDAAwD;AACxD,MAAM,MAAM,mBAAmB,GAAG;IAC9B,qCAAqC;IACrC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAA;IACtB,qBAAqB;IACrB,GAAG,EAAE,MAAM,CAAA;IACX,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAA;CACd,CAAA;AAED,yDAAyD;AACzD,MAAM,MAAM,WAAW,GAAG;IACtB,+BAA+B;IAC/B,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAA;IAC3C,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAA;IACb,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAA;IACd,uDAAuD;IACvD,KAAK,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;CAChC,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,KAAK,GAAG;IAChB,8BAA8B;IAC9B,GAAG,EAAE,MAAM,CAAA;IACX,oEAAoE;IACpE,OAAO,EAAE,KAAK,CAAC,WAAW,CAAC,CAAA;IAC3B,oEAAoE;IACpE,eAAe,EAAE,KAAK,CAAC,mBAAmB,CAAC,CAAA;IAC3C,iDAAiD;IACjD,QAAQ,EAAE,OAAO,CAAA;IACjB,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAA;IACX,wDAAwD;IACxD,MAAM,CAAC,EAAE,KAAK,CAAA;CACjB,CAAA"}

package/dist/wix.d.ts

@@ -1,6 +1,33 @@
 type REMOVED = 'REMOVED';
+/**
+ * Wix framework props.
+ *
+ * @example
+ * ```tsx
+ * import type { Wix } from '@wix/editor-react-types';
+ *
+ * interface MyComponentProps {
+ *   className: string;
+ *   wix?: Wix;
+ * }
+ *
+ * const MyComponent = ({ className, wix }: MyComponentProps) => (
+ *   <div {...wix?.presetsWrapperProps}>
+ *     <div className={className}>...</div>
+ *   </div>
+ * );
+ * ```
+ */
 export interface Wix {
+    /**
+     * Tracks which removable elements have been removed by the Wix user.
+     * Keys are element keys (as defined in the manifest), values are `'REMOVED'`.
+     */
     elementsRemovalState: Record<string, REMOVED>;
+    /**
+     * Props to spread onto the outermost wrapper element when using presets.
+     * Required for the preset picker to work correctly in the editor.
+     */
     presetsWrapperProps?: {
         className: string;
     };

package/dist/wix.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wix.d.ts","sourceRoot":"","sources":["../src/wix.ts"],"names":[],"mappings":"AAAA,KAAK,OAAO,GAAG,SAAS,CAAA;AACxB,MAAM,WAAW,GAAG;IAChB,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7C,mBAAmB,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;CAC9C"}
+{"version":3,"file":"wix.d.ts","sourceRoot":"","sources":["../src/wix.ts"],"names":[],"mappings":"AAAA,KAAK,OAAO,GAAG,SAAS,CAAA;AAExB;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,GAAG;IAChB;;;OAGG;IACH,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7C;;;OAGG;IACH,mBAAmB,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;CAC9C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/editor-react-types",
-  "version": "1.0.1",
+  "version": "1.0.14",
   "description": "React types for Wix Editor components",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,7 +12,8 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsc -b . --force",
+    "build": "tsc -b . --force && npm run docs",
+    "docs": "docs-ts-model --entryPoint src/index.ts",
     "lint": "yarn run -T lint:package $npm_package_name",
     "test": "yarn test-type-check && vitest --run",
     "test-type-check": "tsc --project tsconfig.test.json",
@@ -22,6 +23,7 @@
     "react": "^18.3.1"
   },
   "devDependencies": {
+    "@wix/docs-ts-model": "^1.0.0",
     "typescript": "^5.3.3",
     "vitest": "^4.0.10"
   },
@@ -35,7 +37,9 @@
       "groupId": "com.wixpress.npm",
       "artifactId": "editor-react-types",
       "targets": {
-        "docker": false
+        "docker": false,
+        "static": true,
+        "build-docs": true
       }
     },
     "validations": {
@@ -46,5 +50,5 @@
     }
   },
   "type": "module",
-  "falconPackageHash": "3aafd078bebde894e3b9becff2fb8ce5d77451c4f6ddab6789ab41f5"
+  "falconPackageHash": "309e0eb6391020770a9d76442b4ae2b980691d2a54bd694352c44602"
 }

package/src/a11y.ts

@@ -1,27 +1,72 @@
+/**
+ * Accessibility attributes.
+ *
+ * @example
+ * ```tsx
+ * import type { A11y } from '@wix/editor-react-types';
+ *
+ * interface MyComponentProps {
+ *   a11y?: A11y;
+ * }
+ *
+ * const MyComponent = ({ a11y }: MyComponentProps) => (
+ *   <div
+ *     tabIndex={a11y?.tabIndex}
+ *     role={a11y?.role}
+ *     aria-label={a11y?.ariaLabel}
+ *   />
+ * );
+ * ```
+ */
 export interface A11y {
+    /** The `tabindex` attribute. Controls the component's position in keyboard focus order. */
     tabIndex?: number
+    /** The `aria-level` attribute. Defines the hierarchical level of a component within a structure. */
     ariaLevel?: number
+    /** The `aria-expanded` attribute. Indicates whether a collapsible component is expanded or collapsed. */
     ariaExpanded?: boolean | 'false' | 'true'
+    /** The `aria-disabled` attribute. Indicates that the component is perceivable but disabled. */
     ariaDisabled?: boolean | 'false' | 'true'
+    /** The `aria-atomic` attribute. Indicates whether assistive technologies should present the entire region as a whole. */
     ariaAtomic?: boolean | 'false' | 'true'
+    /** The `aria-hidden` attribute. Hides the component from assistive technologies. */
     ariaHidden?: boolean | 'false' | 'true'
+    /** The `aria-busy` attribute. Indicates the component is being modified and assistive technologies should wait. */
     ariaBusy?: boolean | 'false' | 'true'
+    /** Whether the component supports multiline input. */
     multiline?: boolean
+    /** The `aria-autocomplete` attribute. Indicates the type of autocomplete behavior for an input. */
     ariaAutocomplete?: 'none' | 'inline' | 'list' | 'both'
+    /** The `aria-pressed` attribute. Indicates the current "pressed" state of a toggle button. */
     ariaPressed?: boolean | 'false' | 'mixed' | 'true'
+    /** The `aria-haspopup` attribute. Indicates the availability and type of an interactive popup component. */
     ariaHaspopup?: boolean | 'false' | 'true' | 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog'
+    /** The `aria-relevant` attribute. Indicates what notifications the user agent will trigger when the accessibility tree is modified. */
     ariaRelevant?: 'additions' | 'additions text' | 'all' | 'removals' | 'text'
+    /** The `role` attribute. Defines the semantic role of the component. */
     role?: string
+    /** The `aria-live` attribute. Indicates that the component will be updated and describes the types of updates. */
     ariaLive?: 'off' | 'assertive' | 'polite'
+    /** The `aria-current` attribute. Indicates the component that represents the current item within a container or set. */
     ariaCurrent?: boolean | 'false' | 'true' | 'page' | 'step' | 'location' | 'date' | 'time'
+    /** The `aria-label` attribute. Defines a string value that labels the component. */
     ariaLabel?: string
+    /** The `aria-roledescription` attribute. Defines a human-readable description for the role of the component. */
     ariaRoledescription?: string
+    /** The `aria-describedby` attribute. Identifies the element that describes this component. */
     ariaDescribedby?: string
+    /** The `aria-labelledby` attribute. Identifies the element that labels this component. */
     ariaLabelledby?: string
+    /** The `aria-errormessage` attribute. Identifies the element that provides an error message for this component. */
     ariaErrormessage?: string
+    /** The `aria-owns` attribute. Identifies a component to define a visual, functional, or contextual parent/child relationship. */
     ariaOwns?: string
+    /** The `aria-controls` attribute. Identifies the element whose contents or presence are controlled by this component. */
     ariaControls?: string
+    /** The HTML tag to render the component as (e.g. `'h1'`, `'button'`). */
     tag?: string
+    /** The `aria-multiline` attribute. Indicates whether a text box accepts multiple lines of input. */
     ariaMultiline?: boolean | 'false' | 'true'
+    /** The `aria-invalid` attribute. Indicates the entered value does not conform to the expected format. */
     ariaInvalid?: boolean | 'false' | 'true' | 'grammar' | 'spelling'
 }

package/src/audio.ts

@@ -1,12 +1,38 @@
+/** A single audio source file at a specific quality and format. */
+export type AudioSource = {
+    /** The audio bitrate in kbps. */
+    audioBitrate: number
+    /** The audio format (e.g. `'mp3'`, `'ogg'`). */
+    format: string
+    /** The audio quality label. */
+    quality: string
+    /** The fully resolved audio URL. */
+    url: string
+}
+
+/**
+ * An audio track from Wix Media.
+ *
+ * @example
+ * ```tsx
+ * import type { Audio } from '@wix/editor-react-types';
+ *
+ * interface MyComponentProps {
+ *   audio?: Audio;
+ * }
+ * ```
+ */
 export type Audio = {
-    // WixMedia ID.
-    id: string
-    // Audio URL.
+    /** The fully resolved audio URL. */
     url: string
-    // Audio filename.
-    filename: string
-    // Audio length in seconds.
-    duration: number
-    // Audio title
-    title: string
+    /** The audio artist name. */
+    artist?: string
+    /** The audio track title. */
+    title?: string
+    /** The audio duration in seconds. */
+    duration?: number
+    /** The audio file name. */
+    name?: string
+    /** All available audio sources at different quality levels and formats. */
+    audio?: Array<AudioSource>
 }

package/src/base.ts

@@ -1,3 +1,8 @@
+/**
+ * @module
+ * Primitive and base data types for component props.
+ */
+
 import type { ReactNode, FC } from 'react'
 
 import type { Link } from './links'
@@ -7,32 +12,294 @@ import type { VectorArt } from './vectorArt'
 import type { A11y } from './a11y'
 import type { Audio } from './audio'
 
-export type Text = string // A simple text value
-
-export type TextEnum = string // The selected value by the user in the editor from the defined option
-export type NumberType = number // Any number
-export type BooleanValue = boolean // true / false value
-
-export type Schema = Record<string, unknown> // A JSON Schema definition
-export type LocalDate = string // Local date output ISO-8601 extended local date format (YYYY-MM-DD)
-export type LocalTime = string // Local time output ISO-8601 extended local time format (hh:mm[:ss][.sss])
-export type LocalDateTime = string // Local Date Time output ISO-8601 extended local date-time format (YYYY-MM-DDThh:mm[:ss][.sss])
-export type WebUrl = string // A URL with scheme http or https
-export type Email = string // Standard email address according to RFC 5321, section 4.1.2
-export type Phone = string // A validation format designed to match phone numbers with common characters
-export type Hostname = string // Hostname according to IANA
-export type Regex = string // A valid regex pattern supplied by the User
-export type Guid = string // A unique identifier
+/**
+ * A plain text string.
+ *
+ * @example
+ * ```tsx
+ * import type { Text } from '@wix/editor-react-types';
+ *
+ * interface MyComponentProps {
+ *   label?: Text;
+ * }
+ * ```
+ */
+export type Text = string
+
+/**
+ * The value selected by the Wix user from a predefined set of options.
+ *
+ * @example
+ * ```tsx
+ * import type { TextEnum } from '@wix/editor-react-types';
+ *
+ * interface MyComponentProps {
+ *   alignment?: TextEnum; // e.g. 'left' | 'center' | 'right'
+ * }
+ * ```
+ */
+export type TextEnum = string
+
+/**
+ * Any numeric value.
+ *
+ * @example
+ * ```tsx
+ * import type { NumberType } from '@wix/editor-react-types';
+ *
+ * interface MyComponentProps {
+ *   rating?: NumberType;
+ * }
+ * ```
+ */
+export type NumberType = number
+
+/**
+ * A boolean `true` or `false` value.
+ *
+ * @example
+ * ```tsx
+ * import type { BooleanValue } from '@wix/editor-react-types';
+ *
+ * interface MyComponentProps {
+ *   showLabel?: BooleanValue;
+ * }
+ * ```
+ */
+export type BooleanValue = boolean
+
+/**
+ * A JSON Schema definition.
+ *
+ * @example
+ * ```tsx
+ * import type { Schema } from '@wix/editor-react-types';
+ *
+ * interface MyComponentProps {
+ *   schema?: Schema;
+ * }
+ * ```
+ */
+export type Schema = Record<string, unknown>
+
+/**
+ * A local date string in ISO-8601 extended format (`YYYY-MM-DD`).
+ *
+ * @example
+ * ```tsx
+ * import type { LocalDate } from '@wix/editor-react-types';
+ *
+ * interface MyComponentProps {
+ *   startDate?: LocalDate; // e.g. '2024-03-15'
+ * }
+ * ```
+ */
+export type LocalDate = string
+
+/**
+ * A local time string in ISO-8601 extended format (`hh:mm[:ss][.sss]`).
+ *
+ * @example
+ * ```tsx
+ * import type { LocalTime } from '@wix/editor-react-types';
+ *
+ * interface MyComponentProps {
+ *   openingTime?: LocalTime; // e.g. '09:00'
+ * }
+ * ```
+ */
+export type LocalTime = string
+
+/**
+ * A local date-time string in ISO-8601 extended format (`YYYY-MM-DDThh:mm[:ss][.sss]`).
+ *
+ * @example
+ * ```tsx
+ * import type { LocalDateTime } from '@wix/editor-react-types';
+ *
+ * interface MyComponentProps {
+ *   eventStart?: LocalDateTime; // e.g. '2024-03-15T09:00'
+ * }
+ * ```
+ */
+export type LocalDateTime = string
+
+/**
+ * A URL with an `http` or `https` scheme.
+ *
+ * @example
+ * ```tsx
+ * import type { WebUrl } from '@wix/editor-react-types';
+ *
+ * interface MyComponentProps {
+ *   website?: WebUrl;
+ * }
+ * ```
+ */
+export type WebUrl = string
+
+/**
+ * A standard email address according to RFC 5321, section 4.1.2.
+ *
+ * @example
+ * ```tsx
+ * import type { Email } from '@wix/editor-react-types';
+ *
+ * interface MyComponentProps {
+ *   contactEmail?: Email;
+ * }
+ * ```
+ */
+export type Email = string
+
+/**
+ * A phone number string, accepting common phone number characters.
+ *
+ * @example
+ * ```tsx
+ * import type { Phone } from '@wix/editor-react-types';
+ *
+ * interface MyComponentProps {
+ *   phoneNumber?: Phone;
+ * }
+ * ```
+ */
+export type Phone = string
+
+/**
+ * A hostname according to IANA standards.
+ *
+ * @example
+ * ```tsx
+ * import type { Hostname } from '@wix/editor-react-types';
+ *
+ * interface MyComponentProps {
+ *   host?: Hostname; // e.g. 'www.example.com'
+ * }
+ * ```
+ */
+export type Hostname = string
+
+/**
+ * A valid regular expression pattern provided by the Wix user.
+ *
+ * @example
+ * ```tsx
+ * import type { Regex } from '@wix/editor-react-types';
+ *
+ * interface MyComponentProps {
+ *   validationPattern?: Regex; // e.g. '^[a-z]+$'
+ * }
+ * ```
+ */
+export type Regex = string
+
+/**
+ * A unique identifier (UUID).
+ *
+ * @example
+ * ```tsx
+ * import type { Guid } from '@wix/editor-react-types';
+ *
+ * interface MyComponentProps {
+ *   itemId?: Guid;
+ * }
+ * ```
+ */
+export type Guid = string
+
+/**
+ * Rich text content with resolved links.
+ *
+ * @example
+ * ```tsx
+ * import type { RichText } from '@wix/editor-react-types';
+ *
+ * interface MyComponentProps {
+ *   description?: RichText;
+ * }
+ *
+ * const MyComponent = ({ description }: MyComponentProps) => (
+ *   <div>
+ *     {description?.html}
+ *     {description?.linkList.map((link) => (
+ *       <a key={link.href} href={link.href}>{link.href}</a>
+ *     ))}
+ *   </div>
+ * );
+ * ```
+ */
 export type RichText = {
-    text: string // The original content of the rich text
-    html: string // The content of the rich text with resolved links
-    linkList: Array<Link> // The list of links in the rich text
+    /** The original rich text content. */
+    text: string
+    /** The HTML content with all links resolved. */
+    html: string
+    /** All links present in the rich text content. */
+    linkList: Array<Link>
 }
-export type Container = ReactNode | FC<Record<string, unknown>> // A container place in the component that will be passed in as {children} or a function prop
+
+/**
+ * A container slot in the component.
+ *
+ * Can be either a `ReactNode` passed as `children`, or a function component
+ * used as a render prop.
+ *
+ * @example
+ * ```tsx
+ * import type { Container } from '@wix/editor-react-types';
+ *
+ * interface MyComponentProps {
+ *   content?: Container;
+ * }
+ *
+ * const MyComponent = ({ content }: MyComponentProps) => (
+ *   <div>
+ *     {typeof content === 'function' ? content({}) : content}
+ *   </div>
+ * );
+ * ```
+ */
+export type Container = ReactNode | FC<Record<string, unknown>>
+
 export type Data = Record<string, DataType>
-export type ArrayItems = Array<DataType | Data> // An array type of data
-export type Direction = 'rtl' | 'ltr' | 'auto' // Selected direction for the component according to the HTML dir attribute
 
+/**
+ * An array of data values or data records.
+ *
+ * @example
+ * ```tsx
+ * import type { ArrayItems } from '@wix/editor-react-types';
+ *
+ * interface MyComponentProps {
+ *   items?: ArrayItems;
+ * }
+ * ```
+ */
+export type ArrayItems = Array<DataType | Data>
+
+/**
+ * The text direction of the component.
+ * Maps to the HTML `dir` attribute.
+ * - `'ltr'` — left to right.
+ * - `'rtl'` — right to left.
+ * - `'auto'` — determined by content.
+ *
+ * @example
+ * ```tsx
+ * import type { Direction } from '@wix/editor-react-types';
+ *
+ * interface MyComponentProps {
+ *   direction?: Direction;
+ * }
+ *
+ * const MyComponent = ({ direction = 'ltr' }: MyComponentProps) => (
+ *   <div dir={direction}>...</div>
+ * );
+ * ```
+ */
+export type Direction = 'rtl' | 'ltr' | 'auto'
+
+/** A union of all supported data types that can be used as component props. */
 export type DataType =
     | Text
     | TextEnum

package/src/builderAudio.ts

@@ -1,25 +1,4 @@
-export type AudioSource = {
-    // The audio bitrate.
-    audioBitrate: number
-    // The audio format.
-    format: string
-    // The audio quality.
-    quality: string
-    // The audio resolved URL.
-    url: string
-}
+import type { Audio } from './audio'
 
-export type BuilderAudio = {
-    // The audio URL.
-    url: string
-    // The audio artist.
-    artist?: string
-    // The audio title.
-    title?: string
-    // The audio duration in seconds.
-    duration?: number
-    // The audio file name.
-    name?: string
-    // The audio sources.
-    audio?: Array<AudioSource>
-}
+/** @deprecated Use Audio instead (should be deleted) */
+export type BuilderAudio = Audio