@ethlete/contentful 4.0.0-next.10 → 4.0.0-next.12

package/generators/migrate-contentful-default-components/migration.js

@@ -0,0 +1,57 @@
+import { formatFiles } from '@nx/devkit';
+import { createMigrationScope } from '../migrate-to-contentful-v5/migration-scope.js';
+import { scanContentfulDefaultComponentsInFile, } from './contentful-default-components.js';
+export const CONTENTFUL_DEFAULT_COMPONENTS_REPORT_PATH = 'contentful-default-components-migration-tasks.md';
+const renderReport = (tasks) => [
+    '# Contentful default components migration tasks',
+    '',
+    'The shipped asset and link components are opt-in. Without them embedded assets are skipped and',
+    'hyperlinks render as plain anchors. The migration spread `CONTENTFUL_DEFAULT_COMPONENTS` into every',
+    'literal `provideContentfulConfig` call; the calls below need it by hand:',
+    '',
+    '```ts',
+    "import { CONTENTFUL_DEFAULT_COMPONENTS, provideContentfulConfig } from '@ethlete/contentful';",
+    '',
+    'provideContentfulConfig({ ...CONTENTFUL_DEFAULT_COMPONENTS });',
+    '```',
+    '',
+    'A config that names every asset and link component itself needs nothing. Delete this file when done.',
+    '',
+    ...tasks.map((task) => [`## \`${task.id}\``, '', `- ${task.file}:${task.line}`, `- ${task.message}`, ''].join('\n')),
+].join('\n');
+export default async function migrateContentfulDefaultComponents(tree, schema) {
+    console.log('\n🔎 Spreading CONTENTFUL_DEFAULT_COMPONENTS into provideContentfulConfig...');
+    const scope = createMigrationScope(tree, schema);
+    console.log(`   Scope: ${scope.describe()}`);
+    const changed = [];
+    const tasks = [];
+    scope.visit(tree, (filePath) => {
+        if (!filePath.endsWith('.ts') || filePath.endsWith('.d.ts'))
+            return;
+        const content = tree.read(filePath, 'utf-8');
+        if (!content)
+            return;
+        const result = scanContentfulDefaultComponentsInFile(filePath, content);
+        tasks.push(...result.tasks);
+        if (result.next !== null) {
+            tree.write(filePath, result.next);
+            changed.push(filePath);
+        }
+    });
+    if (tasks.length > 0) {
+        tree.write(CONTENTFUL_DEFAULT_COMPONENTS_REPORT_PATH, renderReport(tasks));
+    }
+    if (!schema.skipFormat) {
+        await formatFiles(tree);
+    }
+    if (changed.length > 0) {
+        console.log(`\n✅ Spread CONTENTFUL_DEFAULT_COMPONENTS in ${changed.length} file(s).`);
+    }
+    if (tasks.length > 0) {
+        console.log(`\n⚠️  ${tasks.length} call(s) need the default components by hand — see ${CONTENTFUL_DEFAULT_COMPONENTS_REPORT_PATH}.`);
+    }
+    else if (changed.length === 0) {
+        console.log('\n✅ Nothing to do.');
+    }
+}
+//# sourceMappingURL=migration.js.map

package/generators/migrate-contentful-default-components/schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "migrate-contentful-default-components",
+  "title": "Add withContentfulDefaultComponents() to provideContentfulConfig",
+  "type": "object",
+  "properties": {
+    "projects": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Nx projects to migrate. Defaults to every project in the workspace. Every site is rewritten independently, so any scope is safe — use this to keep the diff reviewable.",
+      "alias": "project"
+    },
+    "include": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Path prefixes to migrate, relative to the workspace root (e.g. 'libs/ui'). Unioned with `projects`. Defaults to the whole workspace.",
+      "alias": "includePath"
+    },
+    "skipFormat": {
+      "type": "boolean",
+      "description": "Skip formatting files after migration",
+      "default": false
+    }
+  },
+  "required": []
+}

package/migrations.json

@@ -7,6 +7,14 @@
       "description": "Move to the components picture, the renamed image inputs and the removed renderer internals.",
       "generator": "@ethlete/contentful:migrate-to-contentful-v5",
       "docs": "/contentful/"
+    },
+    {
+      "name": "contentful-default-components",
+      "version": "4.0.0-next.12",
+      "kind": "auto",
+      "description": "Add withContentfulDefaultComponents() to provideContentfulConfig, and report the calls that need it by hand.",
+      "generator": "@ethlete/contentful:migrate-contentful-default-components",
+      "docs": "/contentful/"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethlete/contentful",
-  "version": "4.0.0-next.10",
+  "version": "4.0.0-next.12",
   "license": "MIT",
   "sideEffects": false,
   "peerDependencies": {

package/types/ethlete-contentful.d.ts

@@ -1,8 +1,10 @@
 import * as _angular_core from '@angular/core';
 import { Type, InputSignal, InjectionToken, Provider } from '@angular/core';
+import * as _ethlete_core from '@ethlete/core';
 import { NgClassType } from '@ethlete/core';
 import { GQL } from '@ethlete/query';
 import { Mark, BLOCKS, INLINES, NodeData, Block } from '@contentful/rich-text-types';
+import * as _ethlete_contentful from '@ethlete/contentful';
 import * as _ethlete_components from '@ethlete/components';
 import { PictureSource } from '@ethlete/components';
 import * as _angular_router from '@angular/router';
@@ -13,6 +15,7 @@ type ContentfulGqlAsset = {
         id: string;
     };
     title: string | null;
+    fileName?: string | null;
     contentType: string | null;
     url: string | null;
     description: string | null;
@@ -145,6 +148,7 @@ declare class ContentfulRichTextRendererComponent {
     private renderer;
     private elementRef;
     private config;
+    private document;
     /**
      * The contentful response gotten via their REST api.
      * @see https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/entries/entries-collection
@@ -169,14 +173,18 @@ declare class ContentfulRichTextRendererComponent {
     private runDeleteInstruction;
     private getComponentRootNode;
     private findParent;
-    private findFollowingElement;
-    private renderInsertOrAppend;
+    private renderInsertAfter;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<ContentfulRichTextRendererComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<ContentfulRichTextRendererComponent, "et-contentful-rich-text-renderer", never, { "content": { "alias": "content"; "required": true; "isSignal": true; }; "richTextPath": { "alias": "richTextPath"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 declare const isRichTextRootNode: (node: unknown) => node is RichTextResponse;
-declare const translateContentfulNodeTypeToHtmlTag: (nodeType: "text" | BLOCKS | INLINES) => "hr" | "blockquote" | "table" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "p" | "ul" | "ol" | "li" | "tr" | "td" | "th" | "div" | "a" | "span";
+/**
+ * The html element a structural rich text node renders as. A node type without an element
+ * (an unsupported inline or block) falls back to `span` for inlines and `div` otherwise,
+ * with a dev-mode warning.
+ */
+declare const translateContentfulNodeTypeToHtmlTag: (nodeType: "text" | BLOCKS | INLINES) => keyof HTMLElementTagNameMap;
 
 type ContentfulImageResizeBehavior = 'pad' | 'crop' | 'fill' | 'scale' | 'thumb' | 'fit';
 type ContentfulImageFocusArea = 'top' | 'bottom' | 'left' | 'right' | 'center' | 'top_left' | 'top_right' | 'bottom_left' | 'bottom_right' | 'face' | 'faces';
@@ -187,6 +195,7 @@ type ComponentLikeWithLink = Type<{
     href: InputSignal<string>;
     text: InputSignal<string>;
     textClass: InputSignal<string>;
+    anchorClass?: InputSignal<string>;
 }>;
 type ComponentLikeWithContentfulRendererInputs = Type<{
     fields?: InputSignal<any>;
@@ -203,7 +212,8 @@ type ContentfulAssetComponents = {
 };
 type ContentfulConfig = {
     /**
-     * Default components for rendering contentful assets
+     * Components for rendering contentful assets and hyperlinks. Empty unless
+     * `CONTENTFUL_DEFAULT_COMPONENTS` is spread into the config or a component is named here.
      */
     components: ContentfulAssetComponents;
     /**
@@ -245,6 +255,7 @@ type ContentfulConfig = {
         backgroundColor: string | null;
     };
 };
+type ContentfulConfigOptions = Partial<ContentfulConfig>;
 type ContentfulLinkType = 'Space' | 'ContentType' | 'Environment' | 'Entry' | 'Asset' | 'Tag';
 type ContentfulLink<T extends ContentfulLinkType> = {
     type: 'Link';
@@ -306,7 +317,7 @@ type ContentfulRestAsset = {
     fields: {
         title: string;
         description: string;
-        file: ContentfulAssetFileData;
+        file?: ContentfulAssetFileData;
     };
     metadata: ContentfulMetadata;
 };
@@ -349,7 +360,26 @@ declare class ContentfulAudioComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<ContentfulAudioComponent, "et-contentful-audio", never, { "asset": { "alias": "asset"; "required": true; "isSignal": true; }; "audioClass": { "alias": "audioClass"; "required": false; "isSignal": true; }; "figureClass": { "alias": "figureClass"; "required": false; "isSignal": true; }; "figcaptionClass": { "alias": "figcaptionClass"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
+/** Every string `et-contentful-file` renders itself. Override them app-wide with {@link provideContentfulFileLabels}. */
+type ContentfulFileLabels = {
+    /** The size shown after the file title, e.g. `'(1.5 MB)'`. */
+    fileSize: (bytes: number) => string;
+};
+/** The built-in English labels. */
+declare const DEFAULT_CONTENTFUL_FILE_LABELS: ContentfulFileLabels;
+/**
+ * Localize `et-contentful-file` for everything below this injector, and read the set in effect here as a signal.
+ * Partial - whatever you leave out keeps its {@link DEFAULT_CONTENTFUL_FILE_LABELS} value.
+ *
+ * @example
+ * provideContentfulFileLabels({ fileSize: (bytes) => `(${new Intl.NumberFormat('de').format(bytes)} Byte)` });
+ */
+declare const provideContentfulFileLabels: (labels: _ethlete_core.LabelsSource<ContentfulFileLabels>) => _angular_core.Provider;
+declare const injectContentfulFileLabels: () => _angular_core.Signal<ContentfulFileLabels>;
+declare const CONTENTFUL_FILE_LABELS: _angular_core.InjectionToken<_ethlete_core.LabelsSource<ContentfulFileLabels>>;
+
 declare class ContentfulFileComponent {
+    protected labels: _angular_core.Signal<_ethlete_contentful.ContentfulFileLabels>;
     asset: _angular_core.InputSignal<ContentfulGqlAsset | ContentfulRestAsset | null | undefined>;
     fileClass: _angular_core.InputSignal<NgClassType>;
     protected data: _angular_core.Signal<{
@@ -396,22 +426,37 @@ declare const parseContentfulImageSize: (size: string) => {
     width: number | null;
     height: number | null;
 };
-declare const generateContentfulImageSources: (data: ContentfulRestAsset | ContentfulGqlAsset, srcsetSizes: string[], backgroundColor: string | null, quality: number | null, focusArea: ContentfulImageFocusArea | null, resizeBehavior: ContentfulImageResizeBehavior | null) => PictureSource[];
+type ContentfulImageSourcesOptions = {
+    srcsetSizes?: string[];
+    backgroundColor?: string | null;
+    quality?: number | null;
+    focusArea?: ContentfulImageFocusArea | null;
+    resizeBehavior?: ContentfulImageResizeBehavior | null;
+};
+/**
+ * Builds AVIF and WebP `<source>` entries for a Contentful asset through the Contentful Images API.
+ *
+ * @example
+ * generateContentfulImageSources(asset, { srcsetSizes: ['400w', '800w'], quality: 80 });
+ */
+declare const generateContentfulImageSources: (data: ContentfulRestAsset | ContentfulGqlAsset, options?: ContentfulImageSourcesOptions) => PictureSource[];
 
 declare class ContentfulLinkComponent {
     private document;
     private router;
     private config;
+    private url;
     href: _angular_core.InputSignal<string>;
     text: _angular_core.InputSignal<string>;
     textClass: _angular_core.InputSignal<string>;
+    anchorClass: _angular_core.InputSignal<string>;
     protected usesRouterLink: _angular_core.Signal<boolean>;
     protected openInNewTab: _angular_core.Signal<boolean>;
     protected internalPath: _angular_core.Signal<string>;
     protected internalUrlTree: _angular_core.Signal<_angular_router.UrlTree>;
-    protected linkClass: _angular_core.Signal<string>;
+    protected linkClass: _angular_core.Signal<string | null>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<ContentfulLinkComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ContentfulLinkComponent, "et-contentful-link", never, { "href": { "alias": "href"; "required": true; "isSignal": true; }; "text": { "alias": "text"; "required": true; "isSignal": true; }; "textClass": { "alias": "textClass"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ContentfulLinkComponent, "et-contentful-link", never, { "href": { "alias": "href"; "required": true; "isSignal": true; }; "text": { "alias": "text"; "required": true; "isSignal": true; }; "textClass": { "alias": "textClass"; "required": false; "isSignal": true; }; "anchorClass": { "alias": "anchorClass"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 declare class ContentfulVideoComponent {
@@ -429,15 +474,33 @@ declare const CONTENTFUL_CONFIG: InjectionToken<ContentfulConfig>;
 
 declare const ContentfulImports: readonly [typeof ContentfulAudioComponent, typeof ContentfulFileComponent, typeof ContentfulImageComponent, typeof ContentfulVideoComponent, typeof ContentfulRichTextRendererComponent];
 
-declare const createContentfulConfig: (config?: Partial<ContentfulConfig> | null) => ContentfulConfig;
+declare const createContentfulConfig: (options?: ContentfulConfigOptions | null) => ContentfulConfig;
 /**
  * Reads the contentful config from the current injector. Falls back to a config without
  * any `components` when none was provided via `provideContentfulConfig()`.
  */
 declare const injectContentfulConfig: () => ContentfulConfig;
 
-declare const provideContentfulConfig: (contentfulConfig?: Partial<ContentfulConfig> | null) => Provider;
+/**
+ * The shipped audio, file, image, video and link components, to spread into `provideContentfulConfig`.
+ * An app that brings its own components, or renders text only, leaves this out and bundles none of them.
+ * To replace one, spread the map instead: `components: { ...CONTENTFUL_DEFAULT_COMPONENTS.components, image: MyImage }`.
+ *
+ * @example
+ * provideContentfulConfig({ ...CONTENTFUL_DEFAULT_COMPONENTS });
+ */
+declare const CONTENTFUL_DEFAULT_COMPONENTS: {
+    components: {
+        audio: typeof ContentfulAudioComponent;
+        file: typeof ContentfulFileComponent;
+        image: typeof ContentfulImageComponent;
+        video: typeof ContentfulVideoComponent;
+        link: typeof ContentfulLinkComponent;
+    };
+};
+
+declare const provideContentfulConfig: (contentfulConfig?: ContentfulConfigOptions | null) => Provider;
 declare const isContentfulEntryType: <T extends ContentfulEntry>(entry: ContentfulEntry, type: string) => entry is T;
 
-export { CONTENTFUL_CONFIG, ContentfulAudioComponent, ContentfulFileComponent, ContentfulImageComponent, ContentfulImports, ContentfulLinkComponent, ContentfulRichTextRendererComponent, ContentfulVideoComponent, ET_CONTENTFUL_ANY_ENTRY_CONTENT_TYPE_SYS_ID, GQL_FRAGMENT_CONTENTFUL_ASSET, createContentfulConfig, createContentfulIncludeMap, generateContentfulImageSources, generateDefaultContentfulImageSource, injectContentfulConfig, isContentfulEntryType, isContentfulGqlAsset, isRichTextRootNode, marksToClass, marksToTags, parseContentfulImageSize, provideContentfulConfig, translateContentfulNodeTypeToHtmlTag };
-export type { ComponentLikeWithAsset, ComponentLikeWithContentfulRendererInputs, ComponentLikeWithLink, ContentfulAssetComponents, ContentfulAssetFileData, ContentfulAssetImageData, ContentfulAssetLink, ContentfulAssetLinkItem, ContentfulCollection, ContentfulConfig, ContentfulContentTypeLink, ContentfulEntry, ContentfulEntryLink, ContentfulEntryLinkItem, ContentfulEntrySys, ContentfulEnvironmentLink, ContentfulGqlAsset, ContentfulGqlCollectionFilterVariables, ContentfulGqlOrder, ContentfulGqlWhereFilter, ContentfulImageFocusArea, ContentfulImageResizeBehavior, ContentfulIncludeMap, ContentfulLink, ContentfulLinkType, ContentfulMetadata, ContentfulRestAsset, ContentfulSpaceLink, ContentfulSys, ContentfulTagLink, ContentfulTagLinkItem, CreateContentfulIncludeMapConfig, RichTextResponse };
+export { CONTENTFUL_CONFIG, CONTENTFUL_DEFAULT_COMPONENTS, CONTENTFUL_FILE_LABELS, ContentfulAudioComponent, ContentfulFileComponent, ContentfulImageComponent, ContentfulImports, ContentfulLinkComponent, ContentfulRichTextRendererComponent, ContentfulVideoComponent, DEFAULT_CONTENTFUL_FILE_LABELS, ET_CONTENTFUL_ANY_ENTRY_CONTENT_TYPE_SYS_ID, GQL_FRAGMENT_CONTENTFUL_ASSET, createContentfulConfig, createContentfulIncludeMap, generateContentfulImageSources, generateDefaultContentfulImageSource, injectContentfulConfig, injectContentfulFileLabels, isContentfulEntryType, isContentfulGqlAsset, isRichTextRootNode, marksToClass, marksToTags, parseContentfulImageSize, provideContentfulConfig, provideContentfulFileLabels, translateContentfulNodeTypeToHtmlTag };
+export type { ComponentLikeWithAsset, ComponentLikeWithContentfulRendererInputs, ComponentLikeWithLink, ContentfulAssetComponents, ContentfulAssetFileData, ContentfulAssetImageData, ContentfulAssetLink, ContentfulAssetLinkItem, ContentfulCollection, ContentfulConfig, ContentfulConfigOptions, ContentfulContentTypeLink, ContentfulEntry, ContentfulEntryLink, ContentfulEntryLinkItem, ContentfulEntrySys, ContentfulEnvironmentLink, ContentfulFileLabels, ContentfulGqlAsset, ContentfulGqlCollectionFilterVariables, ContentfulGqlOrder, ContentfulGqlWhereFilter, ContentfulImageFocusArea, ContentfulImageResizeBehavior, ContentfulImageSourcesOptions, ContentfulIncludeMap, ContentfulLink, ContentfulLinkType, ContentfulMetadata, ContentfulRestAsset, ContentfulSpaceLink, ContentfulSys, ContentfulTagLink, ContentfulTagLinkItem, CreateContentfulIncludeMapConfig, RichTextResponse };