@sveltia/cms 0.21.1 → 0.21.3

package/README.md

@@ -24,17 +24,17 @@ Our goal is to make it a viable successor to Netlify CMS, expand the Git-based h
 
 **Sveltia CMS is still in beta**, so please be careful when trying it out.
 
-While we are fixing reported bugs as fast as we can, the overall progress may be slower than you think. The thing is, it’s not just a personal project of [@kyoshino](https://github.com/kyoshino), but also involves different kinds of activities:
+While we are fixing reported bugs as fast as we can, usually within 48 hours, the overall progress may be slower than you think. The thing is, it’s not just a personal project of [@kyoshino](https://github.com/kyoshino), but also involves different kinds of activities:
 
 - Ensuring maximum compatibility with existing versions of Netlify/Decap CMS
 - Tackling as many [issues reported to Netlify/Decap CMS](https://github.com/decaporg/decap-cms/issues) as possible (so far 75+ of them have been effectively solved in Sveltia CMS, with the goal of reaching 100 by GA)
 - Implementing our own enhancement ideas
 
-At this point **we hope to ship version 1.0 in Q3 2024**. Check our [release notes](https://github.com/sveltia/sveltia-cms/releases) for updates!
+At this point, **we are aiming to ship version 1.0 in Q3 2024**. Check our [release notes](https://github.com/sveltia/sveltia-cms/releases) for updates.
 
 ## Features
 
-We are working hard to create a **much better alternative to Netlify CMS** and Decap CMS by improving everything. Here’s what makes Sveltia CMS different. Look how serious we are!
+We are working hard to create a **significantly better alternative to Netlify CMS** and Decap CMS by improving everything. Here’s what makes Sveltia CMS different. Look how serious we are!
 
 ### Compatible with Netlify/Decap CMS
 
@@ -57,9 +57,9 @@ We are working hard to create a **much better alternative to Netlify CMS** and D
 - Small footprint: The bundle size is less than 500 KB when minified and gzipped, which is much lighter than bloated Netlify CMS (1.5 MB) and Decap CMS (1.8 MB)[^57]. Sveltia CMS is free of technical debt and [virtual DOM overhead](https://svelte.dev/blog/virtual-dom-is-pure-overhead).
 - Uses the GraphQL API for GitHub and GitLab to quickly fetch content at once, so that entries and assets can be listed and searched instantly[^32]. It also avoids the slowness and potential API rate limit violations caused by hundreds of requests with Relation widgets[^14].
 - Saving entries and assets to GitHub is also much faster thanks to the [GraphQL mutation](https://github.blog/changelog/2021-09-13-a-simpler-api-for-authoring-commits/).
-- A list of repository files is cached locally for faster startup and bandwidth savings.
+- Using caching and lazy loading techniques. A list of repository files is stored locally for faster startup and bandwidth savings.
 - Thumbnails of assets, including PDF files, are generated and cached for faster rendering of the Asset Library and other parts of the CMS[^39].
-- Using caching and lazy loading techniques to improve performance.
+- The upcoming [Svelte 5](https://svelte.dev/blog/runes) upgrade is anticipated to deliver a further boost in performance, including accelerated speed and reduced code size.
 
 ### Better productivity
 
@@ -104,7 +104,7 @@ We are working hard to create a **much better alternative to Netlify CMS** and D
 
 ### Better i18n support
 
-- Sveltia CMS was built with a multilingual architecture from the very beginning. You can expect top-notch i18n support.
+- Sveltia CMS has been built with a multilingual architecture from the very beginning. You can expect top-notch i18n support, as it’s required by clients of maintainer [@kyoshino](https://github.com/kyoshino), who himself was a long-time Japanese localizer for Mozilla.
 - You can easily switch between locales while editing with just a click on a button instead of a dropdown list.
 - Fields in non-default locales are validated as expected[^13].
 - Boolean, DateTime, List and Number fields in the entry preview are displayed in a localized format.
@@ -132,6 +132,7 @@ We are working hard to create a **much better alternative to Netlify CMS** and D
 - You can hide the preview of a specific field with `preview: false`.
 - Fields with validation errors are automatically expanded if they are part of nested, collapsed objects[^40].
 - When you click on a field in the Preview pane, the corresponding field in the Editor pane is highlighted. It will be automatically expanded if collapsed[^41].
+- A long validation error message is displayed in full, without being hidden behind the field label[^59].
 
 ### Better data output
 
@@ -150,6 +151,9 @@ We are working hard to create a **much better alternative to Netlify CMS** and D
   - An optional List field with no subfield or value is saved as an empty array, rather than nothing[^44].
   - You can enter spaces in a simple text-based List field[^50].
   - You can preview variable types without having to register a preview template[^42].
+- Markdown
+  - The rich text editor is built with [Lexical](https://github.com/facebook/lexical) instead of [Slate](https://github.com/ianstormtaylor/slate), which solves several problems found in Netlify/Decap CMS, including fatal application crashes[^53].
+  - You can set the default editor mode by changing the order of the `modes` option[^58]. If you want to use the plain text editor by default, add `modes: [raw, rich_text]` to the field configuration.
 - Object
   - Supports [variable types](https://decapcms.org/docs/variable-type-widgets/) just like the List widget. This allows you to have dependent fields in a collection[^30].
   - An optional Object field can be manually added or removed. If unadded or removed, the required subfields won’t trigger validation errors[^16].
@@ -160,27 +164,28 @@ We are working hard to create a **much better alternative to Netlify CMS** and D
 - String
   - Supports the `type` property that accepts `url` or `email` as a value, which will validate the value as a URL or email.
   - Supports the `prefix` and `suffix` string properties, which automatically prepend and/or append the developer-defined value to the user-input value.
-- Markdown
-  - The rich text editor is built with [Lexical](https://github.com/facebook/lexical) instead of [Slate](https://github.com/ianstormtaylor/slate), which solves several problems found in Netlify/Decap CMS, including fatal application crashes[^53].
-  - You can set the default editor mode by changing the order of the `modes` option[^58]. If you want to use the plain text editor by default, add `[raw, rich_text]` to the field configuration.
 - Boolean, Number and String
   - Supports the `before_input` and `after_input` string properties, which allow developers to display custom labels before and/or after the input UI[^28]. Markdown is supported in the value.
-- List and Object
-  - The `summary` is displayed correctly when it refers to a Relation field[^36].
 - File and Image
   - Provides a reimagined all-in-one asset selection dialog for File and Image fields.
     - [Collection-specific assets](#using-a-custom-media-folder-for-a-collection) are listed for easy selection, while all assets are displayed in a separate tab[^19].
     - A new asset can be uploaded by dragging & dropping it into the dialog[^20].
     - A URL can also be entered in the dialog.
     - Integration with Pexels, Pixabay and Unsplash makes it easy to select and insert a free stock photo[^8]. More services will be added later.
-- String, Text and Markdown
+- List and Object
+  - The `summary` is displayed correctly when it refers to a Relation field[^36].
+- Markdown, String and Text
   - A required field containing only spaces or line breaks will result in a validation error, as if no characters were entered.
-- New widgets
+
+#### New widgets
+
+- Compute
+  - The experimental `compute` widget allows to reference the value of other fields in the same collection, similar to the `summary` property for the List and Object widgets. Use the `value` property to define the value template, e.g. `posts-{{fields.slug}}` ([example](https://github.com/sveltia/sveltia-cms/issues/111)).
+- UUID
   - In addition to [generating UUIDs for entry slugs](#using-a-random-id-for-an-entry-slug), Sveltia CMS also supports the proposed `uuid` widget with the following properties[^12]:
     - `prefix`: A string to be prepended to the value. Default: an empty string.
     - `use_b32_encoding`: Whether to encode the value with Base32. Default: `false`.
     - `read_only`: Whether to make the field read-only. Default: `true`.
-  - The experimental `compute` widget allows to reference the value of other fields in the same collection, similar to the `summary` property for the List and Object widgets. Use the `value` property to define the value template, e.g. `posts-{{fields.slug}}` ([example](https://github.com/sveltia/sveltia-cms/issues/111)).
 
 ### Better asset management
 
@@ -203,37 +208,47 @@ We are working hard to create a **much better alternative to Netlify CMS** and D
 
 ## Compatibility
 
-We are trying to make Sveltia CMS as compatible as possible with Netlify/Decap CMS before the 1.0 release, so that more users can seamlessly switch to our modern, powerful alternative. However, some features will be omitted due to performance and other factors. The table below shows the current limitations of Sveltia CMS:
+We are trying to make Sveltia CMS as compatible as possible with Netlify/Decap CMS, so that more users can seamlessly switch to our modern, powerful alternative. However, some features will be omitted due to deprecations and other factors.
+
+### Current limitations
+
+The table below shows the current limitations of Sveltia CMS, that are expected to be resolved before GA:
 
 | Feature | Status in Sveltia CMS |
 | --- | --- |
-| Backends | Only the GitHub and GitLab backends are available. We’ll add the Test backend for our demo site, but Azure, Bitbucket and Gitea are unlikely to be supported due to performance limitations. Netlify Git Gateway will not be supported for the same reason; we may implement a performant alternative sometime later. |
-| Configuration | UI Locales are currently only available in English and Japanese. Comprehensive config validation is not yet implemented. |
-| Media Libraries | We will add support for Cloudinary and Uploadcare soon. Deprecated Netlify Large Media will not be supported. |
+| Backends | Only GitHub and GitLab are available. We’ll add the Test backend for our demo site and see if Azure can also be supported. |
+| Configuration | UI Locales are only available in English and Japanese. Comprehensive config validation is not yet implemented. |
+| Media Libraries | Cloudinary and Uploadcare are not yet supported. |
 | Workflow | Editorial Workflow and Open Authoring are not yet supported. |
 | Content Editor | Auto-saving a draft entry is not yet implemented. |
 | Collections | Nested collections are not yet supported. |
-| Widgets | Custom widgets are not yet supported. [See below](#widget-limitations) for other limitations. |
+| Widgets | Custom widgets are not yet supported. See the table below for other limitations. |
 | Customizations | Custom previews, custom formatters and event subscriptions are not yet supported. |
 
-### Widget limitations
-
 | Widget | Status in Sveltia CMS |
 | --- | --- |
 | Code | Not yet supported. |
-| Date | Sveltia CMS has dropped the support for the deprecated widget following Decap CMS 3.0. Use the DateTime widget instead. |
 | DateTime | The `date_format` and `time_format` options with Moment.js tokens are not yet supported. Note: Decap CMS 3.1 has replaced Moment.js with [Day.js](https://day.js.org/); we’ll follow the change soon. |
 | File/Image | Field-specific media folders and media library options are not yet supported other than `media_library.config.max_file_size` for the default media library. |
 | Map | Not yet supported. |
-| Markdown | Editor components are not yet supported. Remark plugins will not be supported as they are not compatible with our Lexical-based rich text editor. |
+| Markdown | Editor components are not yet supported. |
+
+### Features not to be implemented
+
+- The deprecated client-side implicit grant for the GitLab backend will not be supported, as it has already been [removed from GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/344609). Use the client-side PKCE authorization instead.
+- The Bitbucket, Gitea/Forgejo and Git Gateway backends will not be supported due to performance limitations. We may implement a performant Git Gateway alternative in the future.
+- The Netlify Identity Widget will not be supported, as it’s not useful without Git Gateway.
+- The deprecated Netlify Large Media service will not be supported. Consider other storage providers.
+- Sveltia CMS has dropped the support for the deprecated Date widget following Decap CMS 3.0. Use the DateTime widget instead.
+- Remark plugins will not be supported, as they are not compatible with our Lexical-based rich text editor.
 
 ## Roadmap
 
 ### Before the 1.0 release
 
+- Enhanced compatibility with Netlify/Decap CMS (see above for the status)
+- Automation test coverage (Vitest + Playwright)
 - [Svelte 5](https://svelte.dev/blog/runes) migration
-- Automation test coverage
-- Further Netlify/Decap CMS compatibility, including Editorial Workflow
 - Localization
 - Documentation
 - Marketing site
@@ -295,10 +310,18 @@ If you’ve chosen to install with npm, updating the package is your responsibil
 
 ## Tips & tricks
 
+### Migrating from Git Gateway backend
+
+Sveltia CMS does not support the Git Gateway backend (and Netlify Identity) due to performance limitations. If you don’t care about user management, you can easily migrate to the [GitHub backend](https://decapcms.org/docs/github-backend/) or [GitLab backend](https://decapcms.org/docs/gitlab-backend/). Make sure **you install an OAuth client** on GitHub or GitLab in addition to updating your configuration file. As noted in the document, Netlify still facilitates the auth flow.
+
 ### Moving your site from Netlify to another hosting service
 
 You can host your Sveltia CMS-managed site anywhere, such as [Cloudflare Pages](https://pages.cloudflare.com/) or [GitHub Pages](https://pages.github.com/). But moving away from Netlify means you can no longer sign in with GitHub or GitLab via Netlify. Instead, you can use [our own OAuth client](https://github.com/sveltia/sveltia-cms-auth), which can be easily deployed to Cloudflare Workers, or [any other 3rd party client](https://decapcms.org/docs/external-oauth-clients/) made for Netlify/Decap CMS.
 
+### Working around authentication error
+
+If you get an “Authentication Aborted” error when trying to sign in to GitHub or GitLab using the authorization code flow, you may need to check your site’s [`Cross-Origin-Opener-Policy`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy). The COOP header is not widely used, but it breaks the OAuth flow with a popup window. If that’s your case, changing `same-origin` to `same-origin-allow-popups` solves the problem. ([Discussion](https://github.com/sveltia/sveltia-cms/issues/131))
+
 ### Working with a local Git repository
 
 You can use Sveltia CMS with a local Git repository like [Netlify/Decap CMS](https://decapcms.org/docs/working-with-a-local-git-repository/), but Sveltia CMS has simplified the workflow by removing the need for additional configuration (the `local_backend` property) and a proxy server, thanks to the [File System Access API](https://developer.chrome.com/articles/file-system-access/) available in [some modern browsers](https://developer.mozilla.org/en-US/docs/web/api/window/showopenfilepicker#browser_compatibility).
@@ -511,6 +534,8 @@ Want to build a website with Sveltia CMS? Maintainer [@kyoshino](https://github.
 
 Since Sveltia CMS is still in beta, we expect various problems. Please [report any bugs to us](https://github.com/sveltia/sveltia-cms/issues/new) so we can make it better for everyone. Feel free to submit feature requests as well. Meanwhile, pull requests may not be accepted for the time being due to limited review resources and the upcoming Svelte 5 migration. As we get closer to the 1.0 release, we’ll be welcoming [localizers](https://github.com/sveltia/sveltia-cms/blob/main/src/lib/locales/README.md).
 
+Tips are always welcome! The project hasn’t set up a sponsorship program, but maintainer [@kyoshino](https://github.com/kyoshino) has a [PayPal account](https://paypal.me/kohei).
+
 ## Related links
 
 - Introducing Sveltia CMS: a short technical presentation by [@kyoshino](https://github.com/kyoshino) during the _This Week in Svelte_ online meetup on March 31, 2023 — [recording](https://youtu.be/-YjLubiieYs?t=1660) & [slides](https://docs.google.com/presentation/d/1Wi4ty-1AwOp2-zy7LctmzCV4rrdYPfke9NGhO0DdRdM)
@@ -582,3 +607,4 @@ This software is provided “as is” without any express or implied warranty. W
 [^56]: Netlify/Decap CMS [#6515](https://github.com/decaporg/decap-cms/issues/6515)
 [^57]: Netlify/Decap CMS [#328](https://github.com/decaporg/decap-cms/issues/328), [#3853](https://github.com/decaporg/decap-cms/issues/3853)
 [^58]: Netlify/Decap CMS [#5125](https://github.com/decaporg/decap-cms/issues/5125)
+[^59]: Netlify/Decap CMS [#1654](https://github.com/decaporg/decap-cms/issues/1654)