@allejo/decap-extras 0.0.6 → 0.0.8

package/README.md

@@ -31,11 +31,10 @@ npm install decap-cms-core
 
 ### Widget factories
 
-All factory functions follow the same signature: `widget(label, name, options?)`.
+All factory functions follow a similar signature of `widget(label, name, options?)`.
 
 ```ts
 import {
-	RICH_MARKDOWN,
 	boolWidget,
 	imageWidget,
 	INLINE_MARKDOWN,
@@ -44,24 +43,216 @@ import {
 	numberWidget,
 	objectWidget,
 	optional,
+	RICH_MARKDOWN,
 	selectWidget,
 	stringWidget,
 	textWidget,
 } from '@allejo/decap-extras';
 ```
 
-#### Scalar widgets
+#### Widget modifiers
+
+##### `optional(widget)`
+
+Marks a widget field as optional, allowing it to be left empty in DecapCMS. This modifier can be applied to any widget type to make it non-required.
+
+**TypeScript:**
+
+```ts
+optional(stringWidget('Middle Name', 'middleName'));
+```
+
+**YAML Configuration:**
+
+```yaml
+- label: Middle Name
+  name: middleName
+  widget: string
+  required: false # All fields are required by default, so this is necessary to make it optional
+```
+
+**Data Store YAML:**
+
+```yaml
+middleName: # Can be left empty
+```
+
+The `optional` modifier can be used with all widget types including complex ones:
+
+```ts
+optional(
+	objectWidget('Metadata', 'metadata', [stringWidget('Author', 'author')]),
+);
+optional(listWidget('Tags', 'tags', stringWidget('Tag', 'value')));
+```
+
+The `optional` modifier affects both the Decap CMS UI (field is not required) and the derived TypeScript type (field becomes `T | undefined`).
+
+**Learn more:** [DecapCMS Common Widget Options](https://decapcms.org/docs/widgets/#common-widget-options)
+
+#### Primitive widgets
+
+##### `stringWidget(label, name, opts?)`
+
+Creates a single-line text input field for short text content.
+
+**TypeScript:**
+
+```ts
+stringWidget('Title', 'title');
+```
+
+**YAML Configuration:**
+
+```yaml
+- label: Title
+  name: title
+  widget: string
+```
+
+**Data Store YAML:**
+
+```yaml
+title: Welcome to My Blog
+```
+
+Unlike the `textWidget` which provides multi-line input, the string widget is designed for concise, single-line values like titles, slugs, or names.
+
+```ts
+optional(stringWidget('Slug', 'slug'));
+```
+
+**See also:** [`textWidget`](#textwidgetlabel-name-opts), [`markdownWidget`](#markdownwidgetlabel-name-opts)
+**Learn more:** [DecapCMS String Widget Docs](https://decapcms.org/docs/widgets/#string)
+
+##### `textWidget(label, name, opts?)`
+
+Creates a multi-line text input field for longer text content.
+
+**TypeScript:**
+
+```ts
+textWidget('Description', 'description');
+```
+
+**YAML Configuration:**
+
+```yaml
+- label: Description
+  name: description
+  widget: text
+```
+
+**Data Store YAML:**
+
+```yaml
+description: |-
+  This is a longer description that spans
+  multiple lines in the data store.
+```
+
+Unlike the `stringWidget` which provides single-line input, the text widget is designed for paragraphs and multi-line content.
+
+```ts
+optional(textWidget('Notes', 'notes'));
+```
+
+**See also:** [`stringWidget`](#stringwidgetlabel-name-opts), [`markdownWidget`](#markdownwidgetlabel-name-opts)
+**Learn more:** [DecapCMS Text Widget Docs](https://decapcms.org/docs/widgets/#text)
+
+##### `numberWidget(label, name, opts?)`
+
+Creates a numeric input field with optional min, max, and step constraints.
+
+**TypeScript:**
+
+```ts
+numberWidget('Priority', 'priority');
+```
+
+**YAML Configuration:**
+
+```yaml
+- label: Priority
+  name: priority
+  widget: number
+```
+
+**Data Store YAML:**
+
+```yaml
+priority: 1
+```
+
+The number widget provides numeric input capabilities:
+
+```ts
+optional(numberWidget('Views', 'views'));
+```
+
+**Learn more:** [DecapCMS Number Widget Docs](https://decapcms.org/docs/widgets/#number)
+
+##### `boolWidget(label, name, opts?)`
+
+Creates a checkbox input field for boolean values.
+
+**TypeScript:**
+
+```ts
+boolWidget('Published', 'published');
+```
+
+**YAML Configuration:**
+
+```yaml
+- label: Published
+  name: published
+  widget: boolean
+```
+
+**Data Store YAML:**
+
+```yaml
+published: true
+```
+
+The boolean widget creates a checkbox input in the editor:
+
+```ts
+optional(boolWidget('Draft', 'isDraft'));
+```
+
+**Learn more:** [DecapCMS Boolean Widget Docs](https://decapcms.org/docs/widgets/#boolean)
+
+##### `selectWidget(label, name, choices, opts?)`
+
+Creates a dropdown menu with predefined options.
+
+**TypeScript:**
 
 ```ts
-const titleField = stringWidget('Title', 'title');
-const bodyField = textWidget('Body', 'body');
-const countField = numberWidget('Count', 'count');
-const activeField = boolWidget('Active', 'active');
+selectWidget('Status', 'status', ['draft', 'published', 'archived'] as const);
+```
+
+**YAML Configuration:**
+
+```yaml
+- label: Status
+  name: status
+  widget: select
+  options:
+    - draft
+    - published
+    - archived
 ```
 
-#### Select widget
+**Data Store YAML:**
 
-Pass the choices array `as const` to get a narrowed literal union type; omit `as const` to get `string`.
+```yaml
+status: published
+```
+
+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);
@@ -71,64 +262,247 @@ const looseField = selectWidget('Size', 'size', ['sm', 'md', 'lg']);
 // TypeScript type: string
 ```
 
-#### Object widget
+The select widget can be made optional:
 
 ```ts
-const metaField = objectWidget('Meta', 'meta', [
-	stringWidget('Title', 'title'),
-	stringWidget('Description', 'description'),
+optional(
+	selectWidget('Category', 'category', [
+		'tech',
+		'lifestyle',
+		'business',
+	] as const),
+);
+```
+
+**Learn more:** [DecapCMS Select Widget Docs](https://decapcms.org/docs/widgets/#select)
+
+##### `imageWidget(label, name, opts?)`
+
+Creates a file upload field with image preview capabilities.
+
+**TypeScript:**
+
+```ts
+imageWidget('Featured Image', 'featuredImage');
+```
+
+**YAML Configuration:**
+
+```yaml
+- label: Featured Image
+  name: featuredImage
+  widget: image
+```
+
+**Data Store YAML:**
+
+```yaml
+featuredImage: /images/hero.jpg
+```
+
+The image widget provides file upload functionality with image preview. To pass a default transformation (supported by services like Cloudinary), use the `opts` parameter to pass a `media_library` configuration:
+
+```ts
+imageWidget('Hero Image', 'hero');
+optional(imageWidget('Avatar', 'avatar'));
+```
+
+**Learn more:** [DecapCMS Image Widget Docs](https://decapcms.org/docs/widgets/#image)
+
+#### Complex widgets
+
+##### `objectWidget(label, name, fields, opts?)`
+
+Groups multiple fields together as a nested object in the data store.
+
+**TypeScript:**
+
+```ts
+objectWidget('Author', 'author', [
+	stringWidget('Name', 'name'),
+	stringWidget('Email', 'email'),
 ]);
 ```
 
-#### List widget
+**YAML Configuration:**
+
+```yaml
+- label: Author
+  name: author
+  widget: object
+  fields:
+    - label: Name
+      name: name
+      widget: string
+    - label: Email
+      name: email
+      widget: string
+```
+
+**Data Store YAML:**
+
+```yaml
+author:
+  name: Jane Doe
+  email: jane@example.com
+```
+
+This is useful for creating structured data with related properties. Objects can be nested within lists or other objects to create complex data structures:
+
+```ts
+optional(
+	objectWidget('Metadata', 'metadata', [
+		stringWidget('SEO Title', 'seoTitle'),
+		textWidget('Description', 'description'),
+	]),
+);
+```
+
+**Learn more:** [DecapCMS Object Widget Docs](https://decapcms.org/docs/widgets/#object)
+
+##### `listWidget(label, name, field/fields, opts?)`
 
-Pass a single field to get `Array<T>`, or an array of fields to get `Array<{ ... }>`.
+Creates a list widget that can contain either single-field items or multi-field items.
+
+**Single-field list:**
+
+TypeScript:
 
 ```ts
-// Single-field list → Array<string>
-const tagsField = listWidget('Tags', 'tags', stringWidget('Tag', 'tag'));
+listWidget('Tags', 'tags', stringWidget('Tag', 'value'));
+```
+
+YAML Configuration:
+
+```yaml
+- label: Tags
+  name: tags
+  widget: list
+  field:
+    label: Tag
+    name: value
+    widget: string
+```
 
-// Multi-field list → Array<{ label: string; value: string }>
-const tagObjectsField = listWidget('Tag Objects', 'tagObjects', [
-	stringWidget('Label', 'label'),
-	stringWidget('Value', 'value'),
+Data Store YAML:
+
+```yaml
+tags:
+  - value: React
+  - value: TypeScript
+```
+
+**Multi-field list:**
+
+TypeScript:
+
+```ts
+listWidget('Authors', 'authors', [
+	stringWidget('Name', 'name'),
+	imageWidget('Avatar', 'avatar'),
 ]);
 ```
 
-#### Image widget
+YAML Configuration:
+
+```yaml
+- label: Authors
+  name: authors
+  widget: list
+  fields:
+    - label: Name
+      name: name
+      widget: string
+    - label: Avatar
+      name: avatar
+      widget: image
+```
+
+Data Store YAML:
+
+```yaml
+authors:
+  - name: Jane Doe
+    avatar: /images/jane.jpg
+  - name: John Smith
+    avatar: /images/john.jpg
+```
 
-To pass a default transformation (supported by services like Cloudinary), use the `opts` parameter to pass a `media_library` configuration.
+> [!WARNING]
+>
+> When passing an Object widget (e.g., `objectWidget(...)`), this function will unwrap the object and return `Array<{ ... }>`, not `Array<T>`. This is done as a convenience so you don't have an extra layer of nesting in your data structure. For example, by unwrapping the object, you can have a list of items like this:
+>
+> ```yaml
+> listOfItems:
+>   - label: 'Item 1'
+>     value: 'Value 1'
+> ```
+>
+> If the object was not unwrapped, the data structure would look like this:
+>
+> ```yaml
+> listOfItems:
+>   - item:
+>       label: 'Item 1'
+>       value: 'Value 1'
+> ```
+>
+> If you do want the extra nesting, simply wrap the object in an array when passing it to `listWidget()`, like this:
+>
+> ```typescript
+> const nestedField = listWidget('Nested Items', 'nestedItems', [
+> 	objectWidget('Item', 'item', [
+> 		stringWidget('Label', 'label'),
+> 		stringWidget('Value', 'value'),
+> 	]),
+> ]);
+> ```
+
+The list widget can be made optional:
 
 ```ts
-const heroField = imageWidget('Hero Image', 'hero');
+optional(listWidget('Tags', 'tags', stringWidget('Tag', 'value')));
 ```
 
+**Learn more:** [DecapCMS List Widget Docs](https://decapcms.org/docs/widgets/#list)
+
 #### Markdown widget
 
+##### `markdownWidget(label, name, opts?)`
+
+Creates a rich text editor for markdown content.
+
+**TypeScript:**
+
 ```ts
 // Full markdown editor
-const contentField = markdownWidget('Content', 'content');
+markdownWidget('Content', 'content');
 
 // Restricted to bold, italic, lists, links, and quotes — no images or code blocks
-const descriptionField = markdownWidget(
-	'Description',
-	'description',
-	RICH_MARKDOWN,
-);
+markdownWidget('Description', 'description', RICH_MARKDOWN);
 
 // Inline elements only: bold, italic, and links
-const captionField = markdownWidget('Caption', 'caption', INLINE_MARKDOWN);
+markdownWidget('Caption', 'caption', INLINE_MARKDOWN);
 ```
 
-#### Optional fields
+**YAML Configuration:**
 
-Wrap any widget with `optional()` to mark it as not required in both the Decap CMS UI and the derived TypeScript type.
+```yaml
+- label: Content
+  name: content
+  widget: richtext
+```
 
-```ts
-const subtitleField = optional(stringWidget('Subtitle', 'subtitle'));
-// TypeScript type: string | undefined
+**Data Store YAML:**
+
+```yaml
+content: |
+  # Heading
+  This is **bold** and *italic* text with [links](https://example.com).
 ```
 
+**Learn more:** [DecapCMS RichText Widget Docs](https://decapcms.org/docs/widgets/#richtext-beta)
+
 #### Common options
 
 Every factory accepts an optional last argument for [common widget options](https://decapcms.org/docs/widgets/#common-widget-options):
@@ -148,12 +522,12 @@ Define your CMS config using the widget factories and `as const`, then let `Prop
 ```ts
 // cms/config.ts
 import {
-	RICH_MARKDOWN,
 	boolWidget,
 	imageWidget,
 	markdownWidget,
 	objectWidget,
 	optional,
+	RICH_MARKDOWN,
 	selectWidget,
 	stringWidget,
 } from '@allejo/decap-extras';
@@ -449,31 +823,47 @@ export default function Admin({ cssFiles }: Props) {
 }
 ```
 
-
 ## 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      |
+### Widget API reference
+
+#### Widget modifiers
+
+| Function           | Description                                                                                                             |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| `optional(widget)` | Marks a widget field as optional (non-required). [Learn more](https://decapcms.org/docs/widgets/#common-widget-options) |
+
+#### Primitive widgets
+
+| 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`                  |
+| `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` |
+| `imageWidget(label, name, opts?)`           | [`image`](https://decapcms.org/docs/widgets/#image)     | `string`                  |
+
+#### Complex widgets
+
+| Function                                     | Decap widget                                          | TypeScript type  |
+| -------------------------------------------- | ----------------------------------------------------- | ---------------- |
+| `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) | `{ ... }`        |
+
+#### Rich text widgets
+
+| Function                             | Decap widget                                                   | TypeScript type |
+| ------------------------------------ | -------------------------------------------------------------- | --------------- |
+| `markdownWidget(label, name, opts?)` | [`richtext`](https://decapcms.org/docs/widgets/#richtext-beta) | `string`        |
 
 ### Markdown presets
 
-| Constant          | Description                                                   |
-| ----------------- | ------------------------------------------------------------- |
-| `RICH_MARKDOWN`   | Bold, italic, lists, links, quotes. No images or code blocks. |
-| `INLINE_MARKDOWN` | Bold, italic, and links only. No block-level elements.        |
+| Constant          | Description                                                                                                                                                     |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `RICH_MARKDOWN`   | Stripped down markdown editor with bold, italic, lists (bullet + numbered), quotes, and links. No images or code blocks. Rich Text preview only.                |
+| `INLINE_MARKDOWN` | Stripped down markdown widget that allows only inline elements (bold, italic, and links). No block-level elements like lists or quotes. Rich Text preview only. |
 
 ### Type utilities