@allejo/decap-extras 0.0.0

package/README.md

@@ -0,0 +1,270 @@
+# @allejo/decap-extras
+
+A TypeScript utility library for [Decap CMS](https://decapcms.org/) that does two things:
+
+1. **Widget factory functions** — type-safe helpers for building Decap CMS field configuration objects instead of writing raw object literals by hand.
+2. **Type inference utilities** — TypeScript utility types that derive content types directly from your CMS config, so you never have to maintain separate type definitions for your CMS content.
+
+## Installation
+
+```sh
+npm install @allejo/decap-extras
+# or
+pnpm add @allejo/decap-extras
+# or
+yarn add @allejo/decap-extras
+```
+
+This package requires `decap-cms-core` as a peer dependency:
+
+```sh
+npm install decap-cms-core
+```
+
+## Usage
+
+### Widget factories
+
+All factory functions follow the same signature: `widget(label, name, options?)`.
+
+```ts
+import {
+	BARE_MARKDOWN,
+	boolWidget,
+	imageWidget,
+	INLINE_MARKDOWN,
+	listWidget,
+	markdownWidget,
+	numberWidget,
+	objectWidget,
+	optional,
+	selectWidget,
+	stringWidget,
+	textWidget,
+} from '@allejo/decap-extras';
+```
+
+#### Scalar widgets
+
+```ts
+const titleField = stringWidget('Title', 'title');
+const bodyField = textWidget('Body', 'body');
+const countField = numberWidget('Count', 'count');
+const activeField = boolWidget('Active', 'active');
+```
+
+#### Select widget
+
+Pass the choices array `as const` to get a narrowed literal union type; omit `as const` to get `string`.
+
+```ts
+const themeField = selectWidget('Theme', 'theme', ['light', 'dark'] as const);
+// TypeScript type: "light" | "dark"
+
+const looseField = selectWidget('Size', 'size', ['sm', 'md', 'lg']);
+// TypeScript type: string
+```
+
+#### Object widget
+
+```ts
+const metaField = objectWidget('Meta', 'meta', [
+	stringWidget('Title', 'title'),
+	stringWidget('Description', 'description'),
+]);
+```
+
+#### List widget
+
+Pass a single field to get `Array<T>`, or an array of fields to get `Array<{ ... }>`.
+
+```ts
+// Single-field list → Array<string>
+const tagsField = listWidget('Tags', 'tags', stringWidget('Tag', 'tag'));
+
+// Multi-field list → Array<{ label: string; value: string }>
+const tagObjectsField = listWidget('Tag Objects', 'tagObjects', [
+	stringWidget('Label', 'label'),
+	stringWidget('Value', 'value'),
+]);
+```
+
+#### Image widget
+
+`imageWidget` is pre-configured with [Cloudinary](https://cloudinary.com/) as the media library, with default transformations (`fetch_format: auto`, `quality: auto`, `width: 300`, `crop: scale`). You can override these via the `options` parameter.
+
+```ts
+const heroField = imageWidget('Hero Image', 'hero');
+```
+
+#### Markdown widget
+
+```ts
+// Full markdown editor
+const contentField = markdownWidget('Content', 'content');
+
+// Restricted to bold, italic, lists, links, and quotes — no images or code blocks
+const descriptionField = markdownWidget(
+	'Description',
+	'description',
+	BARE_MARKDOWN,
+);
+
+// Inline elements only: bold, italic, and links
+const captionField = markdownWidget('Caption', 'caption', INLINE_MARKDOWN);
+```
+
+#### Optional fields
+
+Wrap any widget with `optional()` to mark it as not required in both the Decap CMS UI and the derived TypeScript type.
+
+```ts
+const subtitleField = optional(stringWidget('Subtitle', 'subtitle'));
+// TypeScript type: string | undefined
+```
+
+#### Common options
+
+Every factory accepts an optional last argument for [common widget options](https://decapcms.org/docs/widgets/#common-widget-options):
+
+```ts
+const slugField = stringWidget('Slug', 'slug', {
+	required: true,
+	hint: 'URL-friendly identifier, e.g. my-page-title',
+	pattern: ['^[a-z0-9-]+$', 'Lowercase letters, numbers, and hyphens only'],
+});
+```
+
+---
+
+### Type inference
+
+Define your CMS config using the widget factories and `as const`, then let `PropsByCollectionAndFile` derive a fully typed content object from it automatically.
+
+```ts
+// cms/config.ts
+import {
+	BARE_MARKDOWN,
+	boolWidget,
+	imageWidget,
+	markdownWidget,
+	objectWidget,
+	optional,
+	selectWidget,
+	stringWidget,
+} from '@allejo/decap-extras';
+
+export const config = {
+	collections: [
+		{
+			label: 'Pages',
+			name: 'pages' as const,
+			files: [
+				{
+					label: 'Home',
+					name: 'home' as const,
+					file: 'content/home.yml',
+					fields: [
+						stringWidget('Title', 'title'),
+						optional(stringWidget('Subtitle', 'subtitle')),
+						imageWidget('Hero Image', 'hero'),
+						markdownWidget('Body', 'body', BARE_MARKDOWN),
+						selectWidget('Theme', 'theme', ['light', 'dark'] as const),
+						objectWidget('SEO', 'seo', [
+							stringWidget('Meta Title', 'metaTitle'),
+							optional(stringWidget('Meta Description', 'metaDescription')),
+						]),
+					],
+				},
+			],
+		},
+	],
+} as const;
+```
+
+```ts
+// components/HomePage.ts
+import type { PropsByCollectionAndFile } from '@allejo/decap-extras';
+
+import type { config } from '@/cms/config';
+
+type HomePageProps = PropsByCollectionAndFile<typeof config, 'pages', 'home'>;
+// Resolves to:
+// {
+//   title: string;
+//   subtitle?: string;
+//   hero: string;
+//   body: string;
+//   theme: "light" | "dark";
+//   seo: {
+//     metaTitle: string;
+//     metaDescription?: string;
+//   };
+// }
+
+function render(page: HomePageProps) {
+	console.log(page.title); // string
+	console.log(page.subtitle); // string | undefined
+	console.log(page.theme); // "light" | "dark"
+	console.log(page.seo.metaTitle); // string
+}
+```
+
+#### Typing reusable widget functions
+
+Use `WidgetTypeFromFactory` to derive a TypeScript type from a widget factory function without duplicating the definition.
+
+```ts
+import type { WidgetTypeFromFactory } from '@allejo/decap-extras';
+import { objectWidget, optional, stringWidget } from '@allejo/decap-extras';
+
+function seoWidget() {
+	return objectWidget('SEO', 'seo', [
+		stringWidget('Meta Title', 'metaTitle'),
+		optional(stringWidget('Meta Description', 'metaDescription')),
+	]);
+}
+
+type SeoWidget = WidgetTypeFromFactory<typeof seoWidget>;
+// { metaTitle: string; metaDescription?: string }
+```
+
+---
+
+## API reference
+
+### Widget functions
+
+| Function                                     | Decap widget                                                   | TypeScript type           |
+| -------------------------------------------- | -------------------------------------------------------------- | ------------------------- |
+| `stringWidget(label, name, opts?)`           | [`string`](https://decapcms.org/docs/widgets/#string)          | `string`                  |
+| `textWidget(label, name, opts?)`             | [`text`](https://decapcms.org/docs/widgets/#text)              | `string`                  |
+| `markdownWidget(label, name, opts?)`         | [`richtext`](https://decapcms.org/docs/widgets/#richtext-beta) | `string`                  |
+| `imageWidget(label, name, opts?)`            | [`image`](https://decapcms.org/docs/widgets/#image)            | `string`                  |
+| `numberWidget(label, name, opts?)`           | [`number`](https://decapcms.org/docs/widgets/#number)          | `number`                  |
+| `boolWidget(label, name, opts?)`             | [`boolean`](https://decapcms.org/docs/widgets/#boolean)        | `boolean`                 |
+| `selectWidget(label, name, choices, opts?)`  | [`select`](https://decapcms.org/docs/widgets/#select)          | literal union or `string` |
+| `listWidget(label, name, field, opts?)`      | [`list`](https://decapcms.org/docs/widgets/#list)              | `Array<T>`                |
+| `listWidget(label, name, fields[], opts?)`   | [`list`](https://decapcms.org/docs/widgets/#list)              | `Array<{ ... }>`          |
+| `objectWidget(label, name, fields[], opts?)` | [`object`](https://decapcms.org/docs/widgets/#object)          | `{ ... }`                 |
+| `optional(widget)`                           | —                                                              | marks field optional      |
+
+### Markdown presets
+
+| Constant          | Description                                                   |
+| ----------------- | ------------------------------------------------------------- |
+| `BARE_MARKDOWN`   | Bold, italic, lists, links, quotes. No images or code blocks. |
+| `INLINE_MARKDOWN` | Bold, italic, and links only. No block-level elements.        |
+
+### Type utilities
+
+| Type                                      | Description                                                                          |
+| ----------------------------------------- | ------------------------------------------------------------------------------------ |
+| `PropsByCollectionAndFile<TConfig, C, F>` | Derives a typed content object from a CMS config for collection `C` and file `F`.    |
+| `WidgetTypeFromFactory<F>`                | Returns the TypeScript content type produced by a widget factory function `F`.       |
+| `OptionalWidget<T>`                       | Brands a `CmsField` as optional (added by `optional()`).                             |
+| `WidgetOpts<T>`                           | The options type for a given widget field type, with `widget` and `fields` stripped. |
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,345 @@
+import { CmsField, CmsFieldBoolean, CmsFieldFileOrImage, CmsFieldList, CmsFieldMarkdown, CmsFieldNumber, CmsFieldObject, CmsFieldSelect, CmsFieldStringOrText } from "decap-cms-core";
+
+//#region src/api.d.ts
+/**
+ * Get a widget's options while excluding keys we're handling (i.e., `widget`,
+ * `fields`) and respect [global common options](https://decapcms.org/docs/widgets/#String#common-widget-options).
+ */
+type WidgetOpts<T extends {
+  widget?: string;
+  fields?: unknown[];
+}> = Omit<T, 'widget' | 'fields'> & {
+  required?: boolean;
+  hint?: string;
+  pattern?: [string, string];
+};
+type OptionalWidget<T extends CmsField> = T & {
+  required: false;
+  __optional: true;
+};
+/**
+ * Recursively expands a type alias into its fully resolved shape.
+ * TypeScript does not eagerly expand type aliases in IDE hover tooltips —
+ * intermediate type aliases like `FieldsToObject<...>` are shown as-is rather
+ * than their resolved structure. Wrapping a type with this helper forces the
+ * IDE to display the fully resolved object shape at every level of nesting.
+ * This has no effect on type safety or runtime behavior; it is purely cosmetic.
+ *
+ * @example
+ * // Without this helper, the IDE may show:
+ * // type SectionWidget = FieldsToObject<[...]>
+ * //
+ * // With this helper, the IDE shows:
+ * // type SectionWidget = {
+ * //   images: Array<{ polaroid: { image: string; altText?: string; caption: string } }>;
+ * //   text: string;
+ * //   imagePosition: "left" | "right";
+ * // }
+ */
+type IDE_HACK_ExpandRecursiveType<T> = T extends infer O ? { [K in keyof O]: O[K] extends object ? IDE_HACK_ExpandRecursiveType<O[K]> : O[K] } : never;
+/**
+ * Recursively finds the first item in a readonly tuple/array whose `Key`
+ * property matches `Value`.
+ *
+ * Resolves to `never` when no matching item exists.
+ *
+ * @example
+ * type Found = Lookup<
+ *   [{ name: "home"; file: "home.yml" }, { name: "about"; file: "about.yml" }],
+ *   "name",
+ *   "about"
+ * >;
+ * // { name: "about"; file: "about.yml" }
+ *
+ * @example
+ * type Missing = Lookup<[{ name: "home"; file: "home.yml" }], "name", "contact">;
+ * // never
+ */
+type Lookup<Array extends readonly unknown[], Key extends string, Value extends string> = Array extends readonly [infer First, ...infer Rest] ? First extends Record<Key, Value> ? First : Lookup<Rest, Key, Value> : never;
+/**
+ * Get all the collection definitions as a data type from a given config.
+ */
+type CollectionTypes<TConfig extends {
+  collections: readonly unknown[];
+}> = TConfig['collections'][number];
+/**
+ * Get all the collection names from `CollectionTypes` as a union of string
+ * literal types to later use with `Lookup<...>`.
+ */
+type CollectionNames<TConfig extends {
+  collections: readonly unknown[];
+}> = CollectionTypes<TConfig> extends {
+  name: infer N;
+} ? N & string : never;
+/**
+ * Get the specific collection structure for a given collection name. For
+ * example, `CollectionByName<Config, "pages">` would resolve to the collection
+ * definition object for the "Pages" collection in the config,
+ * which would look something like,
+ *
+ * ```
+ * {
+ *   label: "Pages",
+ *   name: "pages",
+ *   files: ({
+ *     label: "Home",
+ *     name: "home",
+ *     ...
+ *   })[]
+ * }
+ * ```
+ */
+type CollectionByName<TConfig extends {
+  collections: readonly unknown[];
+}, N extends CollectionNames<TConfig>> = Lookup<TConfig['collections'], 'name', N>;
+/**
+ * Get the specific fields defined for a given page. For example,
+ * `FileByName<"site/pages/home.yml">` will return the fields defined for the
+ * "home.yml" file in the config, which would look something like,
+ *
+ * ```
+ * {
+ *   label: "Welcome Section",
+ *   name: "welcomeSection",
+ *   widget: "object",
+ *   fields: (...)[]
+ * }
+ * ```
+ */
+type FileByName<C extends {
+  files: readonly unknown[];
+}, F extends (C['files'][number] extends {
+  name: infer N;
+} ? N & string : never)> = Lookup<C['files'], 'name', F>;
+/**
+ * The bare minimum that every file definition in the config must have to be
+ * able to look up its fields and translate them to TypeScript types.
+ */
+type CmsCollectionFile = {
+  name: string;
+  file: string;
+  fields: readonly CmsField[];
+};
+/**
+ * Converts an array of `CmsField` definitions into a TypeScript object type,
+ * mapping each field's `name` to its corresponding TypeScript type via
+ * {@link TypeScriptTypeForField}.
+ *
+ * Fields marked as optional (via {@link OptionalWidget}) are emitted as
+ * optional keys (`key?`); all other fields are required.
+ *
+ * @example
+ * type Result = FieldsToObject<[
+ *   { name: "title"; widget: "string" },
+ *   { name: "ending"; widget: "string"; required: false; __optional: true },
+ * ]>;
+ * // { ending?: string } & { title: string }
+ */
+type FieldsToObject<Fields extends readonly CmsField[]> = { [F in Fields[number] as F extends OptionalWidget<F> ? F['name'] : never]?: TypeScriptTypeForField<F> } & { [F in Fields[number] as F extends OptionalWidget<F> ? never : F['name']]: TypeScriptTypeForField<F> };
+/**
+ * Translates the top-level `fields` of a CMS collection file definition into a
+ * TypeScript object type using {@link FieldsToObject}.
+ *
+ * This is the entry point for type generation from a file definition — it
+ * extracts `F["fields"]` and delegates to `FieldsToObject` so that the same
+ * optional/required splitting logic applies uniformly.
+ */
+type FieldsOfFile<F extends CmsCollectionFile> = FieldsToObject<F['fields']>;
+/**
+ * Translate from `widget` types to their corresponding TypeScript types. For
+ * example, a field with `widget: "string"` will be translated to a TypeScript
+ * type of `string`, and a field with `widget: "object"` and nested `fields`
+ * will be recursively translated to a nested object type.
+ *
+ * For `widget: "select"`, if the field's `options` is a readonly tuple of
+ * string literals, the type is narrowed to the union of those literals instead
+ * of a plain `string`.
+ *
+ * Note: This is not an exhaustive mapping of all possible widget types, but it
+ * can be extended as needed.
+ */
+type TypeScriptTypeForField<F extends CmsField> = F['widget'] extends 'string' | 'richtext' | 'text' | 'image' ? string : F['widget'] extends 'number' ? number : F['widget'] extends 'boolean' ? boolean : F['widget'] extends 'select' ? F extends {
+  options: readonly (infer O)[];
+} ? O : string : F['widget'] extends 'list' ? F extends {
+  fields: readonly CmsField[];
+} ? Array<FieldsToObject<F['fields']>> : F extends {
+  field: CmsField;
+} ? Array<TypeScriptTypeForField<F['field']>> : unknown[] : F['widget'] extends 'object' ? F extends {
+  fields: readonly CmsField[];
+} ? FieldsToObject<F['fields']> : Record<string, unknown> : unknown;
+/**
+ * Get all the file names for a given collection name as a union of string
+ * literal types to later use with `Lookup<...>`. For example,
+ * `CollectionItemNames<Config, "pages">` would resolve to the union of all
+ * file names defined in the "Pages" collection, such as `"home" | "about" | ...`.
+ */
+type CollectionItemNames<TConfig extends {
+  collections: readonly unknown[];
+}, C extends CollectionNames<TConfig>> = CollectionByName<TConfig, C> extends {
+  files: readonly unknown[];
+} ? CollectionByName<TConfig, C>['files'][number] extends {
+  name: infer N;
+} ? N & string : never : never;
+/**
+ * Based on a collection's name and the respective file name, return a TypeScript
+ * object presenting the translated DecapCMS widget types into native TypeScript
+ * types.
+ *
+ * @example
+ * import { config } from '@/cms/config';
+ * type MyProps = PropsByCollectionAndFile<typeof config, 'blog', 'post'>;
+ */
+type PropsByCollectionAndFile<TConfig extends {
+  collections: readonly unknown[];
+}, C extends CollectionNames<TConfig>, F extends CollectionItemNames<TConfig, C>> = IDE_HACK_ExpandRecursiveType<CollectionByName<TConfig, C> extends {
+  files: infer Files extends readonly unknown[];
+} ? FieldsOfFile<FileByName<{
+  files: Files;
+}, F & string>> : never>;
+type WidgetFactory = (...args: any[]) => CmsField;
+/**
+ * Given a widget factory function, return the TypeScript type that corresponds
+ * to the `widget` type(s) that the factory produces. For example, if a widget
+ * factory produces a field with `widget: "object"` and nested `fields`, it will
+ * be translated to a nested object type.
+ *
+ * Note: This relies on the widget factories being defined in a way that their
+ * return type is fully inferable by TypeScript.
+ */
+type WidgetTypeFromFactory<F extends WidgetFactory> = IDE_HACK_ExpandRecursiveType<TypeScriptTypeForField<ReturnType<F>>>;
+//#endregion
+//#region src/widgets.d.ts
+declare function optional<T extends CmsField>(widget: T): OptionalWidget<T>;
+declare function boolWidget<T extends string>(label: string, name: T, options?: WidgetOpts<CmsFieldBoolean>): {
+  readonly default?: boolean;
+  readonly required?: boolean;
+  readonly hint?: string;
+  readonly pattern?: [string, string];
+  readonly label: string;
+  readonly name: T;
+  readonly widget: "boolean";
+};
+declare function imageWidget<T extends string>(label: string, name: T, options?: WidgetOpts<CmsFieldFileOrImage>): {
+  readonly media_library: {
+    readonly name: "cloudinary";
+    readonly config: {
+      readonly default_transformations: readonly [readonly [{
+        readonly fetch_format: "auto";
+        readonly width: 300;
+        readonly quality: "auto";
+        readonly crop: "scale";
+      }]];
+    };
+  };
+  readonly default?: string;
+  readonly allow_multiple?: boolean;
+  readonly choose_url?: boolean;
+  readonly config?: any;
+  readonly required?: boolean;
+  readonly hint?: string;
+  readonly pattern?: [string, string];
+  readonly label: string;
+  readonly name: T;
+  readonly widget: "image";
+};
+declare function listWidget<T extends string, F extends CmsField>(label: string, name: T, fields: F, options?: WidgetOpts<CmsFieldList>): {
+  label: string;
+  name: T;
+  widget: 'list';
+  field: F;
+};
+declare function listWidget<T extends string, F extends CmsField[]>(label: string, name: T, fields: F, options?: WidgetOpts<CmsFieldList>): {
+  label: string;
+  name: T;
+  widget: 'list';
+  fields: F;
+};
+declare function markdownWidget<T extends string>(label: string, name: T, options?: WidgetOpts<CmsFieldMarkdown>): {
+  readonly default?: string;
+  readonly minimal?: boolean;
+  readonly buttons?: import("decap-cms-core").CmsMarkdownWidgetButton[];
+  readonly editor_components?: string[];
+  readonly modes?: ("raw" | "rich_text")[];
+  readonly editorComponents?: string[];
+  readonly required?: boolean;
+  readonly hint?: string;
+  readonly pattern?: [string, string];
+  readonly label: string;
+  readonly name: T;
+  readonly widget: "string";
+};
+declare function objectWidget<T extends string, F extends CmsField[]>(label: string, name: T, fields: F, options?: WidgetOpts<CmsFieldObject>): {
+  readonly fields: F;
+  readonly default?: any;
+  readonly collapsed?: boolean;
+  readonly summary?: string;
+  readonly required?: boolean;
+  readonly hint?: string;
+  readonly pattern?: [string, string];
+  readonly label: string;
+  readonly name: T;
+  readonly widget: "object";
+};
+declare function numberWidget<T extends string>(label: string, name: T, options?: WidgetOpts<CmsFieldNumber>): {
+  readonly default?: string | number;
+  readonly value_type?: "int" | "float" | string;
+  readonly min?: number;
+  readonly max?: number;
+  readonly step?: number;
+  readonly valueType?: "int" | "float" | string;
+  readonly required?: boolean;
+  readonly hint?: string;
+  readonly pattern?: [string, string];
+  readonly label: string;
+  readonly name: T;
+  readonly widget: "number";
+};
+declare function selectWidget<T extends string, O extends string[]>(label: string, name: T, choices: O, options?: WidgetOpts<CmsFieldSelect>): {
+  readonly options: O;
+  readonly default?: string | string[];
+  readonly min?: number;
+  readonly max?: number;
+  readonly multiple?: boolean;
+  readonly required?: boolean;
+  readonly hint?: string;
+  readonly pattern?: [string, string];
+  readonly label: string;
+  readonly name: T;
+  readonly widget: "select";
+};
+declare function stringWidget<T extends string>(label: string, name: T, options?: WidgetOpts<CmsFieldStringOrText>): {
+  readonly default?: string;
+  readonly visualEditing?: boolean;
+  readonly required?: boolean;
+  readonly hint?: string;
+  readonly pattern?: [string, string];
+  readonly label: string;
+  readonly name: T;
+  readonly widget: "string";
+};
+declare function textWidget<T extends string>(label: string, name: T, options?: WidgetOpts<CmsFieldStringOrText>): {
+  readonly default?: string;
+  readonly visualEditing?: boolean;
+  readonly required?: boolean;
+  readonly hint?: string;
+  readonly pattern?: [string, string];
+  readonly label: string;
+  readonly name: T;
+  readonly widget: "text";
+};
+/**
+ * Stripped down Markdown widget configuration that does the following:
+ *
+ * - Allows bold, italic, lists (bullet + numbered), quotes
+ * - No images or code block components
+ * - Rich Text preview only
+ */
+declare const BARE_MARKDOWN: WidgetOpts<CmsFieldMarkdown>;
+/**
+ * Stripped down Markdown Widget configuration that allows only inline
+ * elements (e.g., no lists, quotes, or headings) and rich text preview only.
+ */
+declare const INLINE_MARKDOWN: WidgetOpts<CmsFieldMarkdown>;
+//#endregion
+export { BARE_MARKDOWN, INLINE_MARKDOWN, type OptionalWidget, type PropsByCollectionAndFile, type WidgetOpts, type WidgetTypeFromFactory, boolWidget, imageWidget, listWidget, markdownWidget, numberWidget, objectWidget, optional, selectWidget, stringWidget, textWidget };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/api.ts","../src/widgets.ts"],"mappings":"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"}

package/dist/index.mjs

@@ -0,0 +1,128 @@
+//#region src/widgets.ts
+function optional(widget) {
+	return {
+		...widget,
+		required: false,
+		__optional: true
+	};
+}
+function boolWidget(label, name, options) {
+	return {
+		label,
+		name,
+		widget: "boolean",
+		...options ?? {}
+	};
+}
+function imageWidget(label, name, options) {
+	return {
+		label,
+		name,
+		widget: "image",
+		...options ?? {},
+		media_library: {
+			name: "cloudinary",
+			config: { default_transformations: [[{
+				fetch_format: "auto",
+				width: 300,
+				quality: "auto",
+				crop: "scale"
+			}]] }
+		}
+	};
+}
+function listWidget(label, name, fields, options) {
+	return {
+		label,
+		name,
+		widget: "list",
+		...options ?? {},
+		...Array.isArray(fields) ? { fields } : { field: fields }
+	};
+}
+function markdownWidget(label, name, options) {
+	return {
+		label,
+		name,
+		widget: "richtext",
+		...options ?? {}
+	};
+}
+function objectWidget(label, name, fields, options) {
+	return {
+		label,
+		name,
+		widget: "object",
+		...options ?? {},
+		fields
+	};
+}
+function numberWidget(label, name, options) {
+	return {
+		label,
+		name,
+		widget: "number",
+		...options ?? {}
+	};
+}
+function selectWidget(label, name, choices, options) {
+	return {
+		label,
+		name,
+		widget: "select",
+		...options ?? {},
+		options: choices ?? []
+	};
+}
+function stringWidget(label, name, options) {
+	return {
+		label,
+		name,
+		widget: "string",
+		...options ?? {}
+	};
+}
+function textWidget(label, name, options) {
+	return {
+		label,
+		name,
+		widget: "text",
+		...options ?? {}
+	};
+}
+/**
+* Stripped down Markdown widget configuration that does the following:
+*
+* - Allows bold, italic, lists (bullet + numbered), quotes
+* - No images or code block components
+* - Rich Text preview only
+*/
+const BARE_MARKDOWN = {
+	buttons: [
+		"bold",
+		"bulleted-list",
+		"italic",
+		"link",
+		"numbered-list",
+		"quote"
+	],
+	editor_components: [],
+	modes: ["rich_text"]
+};
+/**
+* Stripped down Markdown Widget configuration that allows only inline
+* elements (e.g., no lists, quotes, or headings) and rich text preview only.
+*/
+const INLINE_MARKDOWN = {
+	buttons: [
+		"bold",
+		"italic",
+		"link"
+	],
+	editor_components: [],
+	modes: ["rich_text"]
+};
+
+//#endregion
+export { BARE_MARKDOWN, INLINE_MARKDOWN, boolWidget, imageWidget, listWidget, markdownWidget, numberWidget, objectWidget, optional, selectWidget, stringWidget, textWidget };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/widgets.ts"],"sourcesContent":["import type {\n\tCmsField,\n\tCmsFieldBoolean,\n\tCmsFieldFileOrImage,\n\tCmsFieldList,\n\tCmsFieldMarkdown,\n\tCmsFieldNumber,\n\tCmsFieldObject,\n\tCmsFieldSelect,\n\tCmsFieldStringOrText,\n} from 'decap-cms-core';\n\nimport type { OptionalWidget, WidgetOpts } from './api.js';\n\n// Widget Modifiers\n\nexport function optional<T extends CmsField>(widget: T): OptionalWidget<T> {\n\treturn {\n\t\t...widget,\n\t\trequired: false as const,\n\t\t__optional: true as const,\n\t};\n}\n\n// Primitive Widgets\n\nexport function boolWidget<T extends string>(\n\tlabel: string,\n\tname: T,\n\toptions?: WidgetOpts<CmsFieldBoolean>,\n) {\n\treturn {\n\t\tlabel,\n\t\tname,\n\t\twidget: 'boolean',\n\t\t...(options ?? {}),\n\t} as const satisfies CmsField;\n}\n\nexport function imageWidget<T extends string>(\n\tlabel: string,\n\tname: T,\n\toptions?: WidgetOpts<CmsFieldFileOrImage>,\n) {\n\treturn {\n\t\tlabel,\n\t\tname,\n\t\twidget: 'image',\n\t\t...(options ?? {}),\n\t\tmedia_library: {\n\t\t\tname: 'cloudinary',\n\t\t\tconfig: {\n\t\t\t\tdefault_transformations: [\n\t\t\t\t\t[\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tfetch_format: 'auto',\n\t\t\t\t\t\t\twidth: 300,\n\t\t\t\t\t\t\tquality: 'auto',\n\t\t\t\t\t\t\tcrop: 'scale',\n\t\t\t\t\t\t},\n\t\t\t\t\t],\n\t\t\t\t],\n\t\t\t},\n\t\t},\n\t} as const satisfies CmsField;\n}\n\nexport function listWidget<T extends string, F extends CmsField>(\n\tlabel: string,\n\tname: T,\n\tfields: F,\n\toptions?: WidgetOpts<CmsFieldList>,\n): { label: string; name: T; widget: 'list'; field: F };\nexport function listWidget<T extends string, F extends CmsField[]>(\n\tlabel: string,\n\tname: T,\n\tfields: F,\n\toptions?: WidgetOpts<CmsFieldList>,\n): { label: string; name: T; widget: 'list'; fields: F };\nexport function listWidget<T extends string, F extends CmsField | CmsField[]>(\n\tlabel: string,\n\tname: T,\n\tfields: F,\n\toptions?: WidgetOpts<CmsFieldList>,\n) {\n\treturn {\n\t\tlabel,\n\t\tname,\n\t\twidget: 'list',\n\t\t...(options ?? {}),\n\t\t...(Array.isArray(fields) ? { fields } : { field: fields }),\n\t} as const;\n}\n\nexport function markdownWidget<T extends string>(\n\tlabel: string,\n\tname: T,\n\toptions?: WidgetOpts<CmsFieldMarkdown>,\n) {\n\treturn {\n\t\tlabel,\n\t\tname,\n\t\twidget: 'richtext' as 'string',\n\t\t...(options ?? {}),\n\t} as const satisfies CmsField;\n}\n\nexport function objectWidget<T extends string, F extends CmsField[]>(\n\tlabel: string,\n\tname: T,\n\tfields: F,\n\toptions?: WidgetOpts<CmsFieldObject>,\n) {\n\treturn {\n\t\tlabel,\n\t\tname,\n\t\twidget: 'object',\n\t\t...(options ?? {}),\n\t\tfields,\n\t} as const satisfies CmsField;\n}\n\nexport function numberWidget<T extends string>(\n\tlabel: string,\n\tname: T,\n\toptions?: WidgetOpts<CmsFieldNumber>,\n) {\n\treturn {\n\t\tlabel,\n\t\tname,\n\t\twidget: 'number',\n\t\t...(options ?? {}),\n\t} as const satisfies CmsField;\n}\n\nexport function selectWidget<T extends string, O extends string[]>(\n\tlabel: string,\n\tname: T,\n\tchoices: O,\n\toptions?: WidgetOpts<CmsFieldSelect>,\n) {\n\treturn {\n\t\tlabel,\n\t\tname,\n\t\twidget: 'select',\n\t\t...(options ?? {}),\n\t\toptions: choices ?? [],\n\t} as const satisfies CmsField;\n}\n\nexport function stringWidget<T extends string>(\n\tlabel: string,\n\tname: T,\n\toptions?: WidgetOpts<CmsFieldStringOrText>,\n) {\n\treturn {\n\t\tlabel,\n\t\tname,\n\t\twidget: 'string',\n\t\t...(options ?? {}),\n\t} as const satisfies CmsField;\n}\n\nexport function textWidget<T extends string>(\n\tlabel: string,\n\tname: T,\n\toptions?: WidgetOpts<CmsFieldStringOrText>,\n) {\n\treturn {\n\t\tlabel,\n\t\tname,\n\t\twidget: 'text',\n\t\t...(options ?? {}),\n\t} as const satisfies CmsField;\n}\n\n// Reusable Widget Configurations\n\n/**\n * Stripped down Markdown widget configuration that does the following:\n *\n * - Allows bold, italic, lists (bullet + numbered), quotes\n * - No images or code block components\n * - Rich Text preview only\n */\nexport const BARE_MARKDOWN: WidgetOpts<CmsFieldMarkdown> = {\n\tbuttons: [\n\t\t'bold',\n\t\t'bulleted-list',\n\t\t'italic',\n\t\t'link',\n\t\t'numbered-list',\n\t\t'quote',\n\t],\n\teditor_components: [],\n\tmodes: ['rich_text'],\n};\n\n/**\n * Stripped down Markdown Widget configuration that allows only inline\n * elements (e.g., no lists, quotes, or headings) and rich text preview only.\n */\nexport const INLINE_MARKDOWN: WidgetOpts<CmsFieldMarkdown> = {\n\tbuttons: ['bold', 'italic', 'link'],\n\teditor_components: [],\n\tmodes: ['rich_text'],\n};\n"],"mappings":";AAgBA,SAAgB,SAA6B,QAA8B;CAC1E,OAAO;EACN,GAAG;EACH,UAAU;EACV,YAAY;CACb;AACD;AAIA,SAAgB,WACf,OACA,MACA,SACC;CACD,OAAO;EACN;EACA;EACA,QAAQ;EACR,GAAI,WAAW,CAAC;CACjB;AACD;AAEA,SAAgB,YACf,OACA,MACA,SACC;CACD,OAAO;EACN;EACA;EACA,QAAQ;EACR,GAAI,WAAW,CAAC;EAChB,eAAe;GACd,MAAM;GACN,QAAQ,EACP,yBAAyB,CACxB,CACC;IACC,cAAc;IACd,OAAO;IACP,SAAS;IACT,MAAM;GACP,CACD,CACD,EACD;EACD;CACD;AACD;AAcA,SAAgB,WACf,OACA,MACA,QACA,SACC;CACD,OAAO;EACN;EACA;EACA,QAAQ;EACR,GAAI,WAAW,CAAC;EAChB,GAAI,MAAM,QAAQ,MAAM,IAAI,EAAE,OAAO,IAAI,EAAE,OAAO,OAAO;CAC1D;AACD;AAEA,SAAgB,eACf,OACA,MACA,SACC;CACD,OAAO;EACN;EACA;EACA,QAAQ;EACR,GAAI,WAAW,CAAC;CACjB;AACD;AAEA,SAAgB,aACf,OACA,MACA,QACA,SACC;CACD,OAAO;EACN;EACA;EACA,QAAQ;EACR,GAAI,WAAW,CAAC;EAChB;CACD;AACD;AAEA,SAAgB,aACf,OACA,MACA,SACC;CACD,OAAO;EACN;EACA;EACA,QAAQ;EACR,GAAI,WAAW,CAAC;CACjB;AACD;AAEA,SAAgB,aACf,OACA,MACA,SACA,SACC;CACD,OAAO;EACN;EACA;EACA,QAAQ;EACR,GAAI,WAAW,CAAC;EAChB,SAAS,WAAW,CAAC;CACtB;AACD;AAEA,SAAgB,aACf,OACA,MACA,SACC;CACD,OAAO;EACN;EACA;EACA,QAAQ;EACR,GAAI,WAAW,CAAC;CACjB;AACD;AAEA,SAAgB,WACf,OACA,MACA,SACC;CACD,OAAO;EACN;EACA;EACA,QAAQ;EACR,GAAI,WAAW,CAAC;CACjB;AACD;;;;;;;;AAWA,MAAa,gBAA8C;CAC1D,SAAS;EACR;EACA;EACA;EACA;EACA;EACA;CACD;CACA,mBAAmB,CAAC;CACpB,OAAO,CAAC,WAAW;AACpB;;;;;AAMA,MAAa,kBAAgD;CAC5D,SAAS;EAAC;EAAQ;EAAU;CAAM;CAClC,mBAAmB,CAAC;CACpB,OAAO,CAAC,WAAW;AACpB"}

package/package.json

@@ -0,0 +1,45 @@
+{
+	"name": "@allejo/decap-extras",
+	"version": "0.0.0",
+	"description": "A TypeScript utility library for Decap CMS with utility types to derive types from Decap CMS configuration files.",
+	"keywords": [
+		"decapcms"
+	],
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/allejo/decap-extras"
+	},
+	"license": "MIT",
+	"author": "Vladimir \"allejo\" Jimenez",
+	"type": "module",
+	"main": "./dist/index.mjs",
+	"types": "./dist/index.d.mts",
+	"scripts": {
+		"build": "tsdown",
+		"format": "prettier --write .",
+		"test": "vitest run --typecheck"
+	},
+	"lint-staged": {
+		"*.{md,ts}": "prettier --write",
+		"*.ts": "eslint --fix"
+	},
+	"devDependencies": {
+		"@allejo/prettier-config": "^1.0.8",
+		"@commitlint/cli": "^18.6.0",
+		"@commitlint/config-conventional": "^18.6.0",
+		"@commitlint/types": "^21.0.1",
+		"@types/eslint": "^8.44.7",
+		"@types/node": "^24.12.4",
+		"decap-cms-app": "^3.12.2",
+		"eslint": "^9.21.0",
+		"husky": "^9.0.10",
+		"lint-staged": "^15.4.3",
+		"prettier": "^3.1.1",
+		"tsdown": "^0.22.0",
+		"typescript": "^5.9.3",
+		"vitest": "^3.2.4"
+	},
+	"peerDependencies": {
+		"decap-cms-core": "^3.12.2"
+	}
+}