@cms-93/react 0.0.0-stage → 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 93GRADOS STUDIO
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,34 @@
1
- # Temporary Holding Version
1
+ # @cms-93/react
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ > **Preview release (0.0.x).** cms-93 is in early development: the API and the content format may change in any release, without notice. Pin the exact version in your `package.json` and read the changelog before updating.
4
+
5
+ React adapter: the website reads its content from cms-93 without React overwriting the editor's changes.
6
+
7
+ License: MIT (see `LICENSE`).
8
+
9
+ ```jsx
10
+ import content from 'virtual:cms-93/content' // with @cms-93/vite
11
+ import { CmsProvider, Editable, EditableImage } from '@cms-93/react'
12
+
13
+ export function App() {
14
+ return (
15
+ <CmsProvider content={content} locale="es">
16
+ <Editable as="h1" name="home.title" max={60}>Design that leaves a mark</Editable>
17
+ <EditableImage name="home.photo" src="/team.jpg" alt="The team" ratio="4/5" width={800} />
18
+ </CmsProvider>
19
+ )
20
+ }
21
+ ```
22
+
23
+ - `<CmsProvider content locale>` gives the components inside it the content in one locale. `content` is the content document (`null` without cms-93) and `locale` the page's language: `es-ES` reads `es`, and one the website doesn't have reads its default locale.
24
+ - `<Editable name as max>` is an editable text: the content of its key or, without it, its children. The rest of its props go to the element.
25
+ - `<EditableImage name src alt ratio>` is an editable `<img>`: the image of its key (file, alternative text, focal point and fit) or its own `src` and `alt`. Its `srcSet` and `sizes` stay only while it shows its own file.
26
+ - `useContent()` gives the content to any component: `text(key, initial)` is the HTML of a text and `image(key, initial)` an image. For a website with its own `t()`, this is where it reads. A text may have `<strong>` and `<em>`: for an attribute or a `<title>`, `toPlainText()` of `@cms-93/core` takes them out.
27
+
28
+ ## In the editor
29
+
30
+ `<Editable>` sets its text as HTML, so React leaves the element's inside alone while its value doesn't change, and what is typed in the editor stays when React renders again. If React mounts the element again (another route, a condition), the editor shows its changes in it again.
31
+
32
+ Children should be plain text, as in the example. Other children (`<strong>` in JSX) are shown until the text has a value; once the editor writes in the element, React may lose track of them if it renders them again.
33
+
34
+ Animations should stop in edit mode: `isEditing()` of `@cms-93/core`, or `html[data-cms-editing]` in CSS.
package/package.json CHANGED
@@ -1,6 +1,35 @@
1
1
  {
2
2
  "name": "@cms-93/react",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.0.1",
4
+ "description": "React adapter: the website reads its content from cms-93 without React overwriting the editor's changes.",
5
+ "type": "module",
6
+ "license": "MIT",
7
+ "exports": {
8
+ ".": "./src/index.js"
9
+ },
10
+ "files": [
11
+ "src"
12
+ ],
13
+ "publishConfig": {
14
+ "access": "public"
15
+ },
16
+ "sideEffects": false,
17
+ "dependencies": {
18
+ "@cms-93/core": "0.0.1"
19
+ },
20
+ "peerDependencies": {
21
+ "react": ">=18"
22
+ },
23
+ "peerDependenciesMeta": {
24
+ "react": {
25
+ "optional": true
26
+ }
27
+ },
28
+ "devDependencies": {
29
+ "react": "^19.3.1",
30
+ "react-dom": "^19.3.1"
31
+ },
32
+ "scripts": {
33
+ "test": "node --test"
34
+ }
6
35
  }
@@ -0,0 +1,27 @@
1
+ import { createContext, createElement, useContext, useMemo } from 'react'
2
+ import { createContentReader } from '@cms-93/core'
3
+
4
+ /** @typedef {import('@cms-93/core').ContentReader} ContentReader */
5
+
6
+ /** Without a provider, everything shows what the code says. */
7
+ const ContentContext = createContext(createContentReader(null, null))
8
+
9
+ /**
10
+ * Gives the components inside it the website's content in one locale.
11
+ * @param {{ content: unknown, locale?: string | null, children?: import('react').ReactNode }} props
12
+ * `content` is the content document (`virtual:cms-93/content`, or `null` without cms-93);
13
+ * `locale`, the page's language: `es-ES` reads `es`, and one the website doesn't have reads its default locale.
14
+ */
15
+ export function CmsProvider({ content, locale = null, children }) {
16
+ const reader = useMemo(() => createContentReader(content, locale), [content, locale])
17
+ return createElement(ContentContext.Provider, { value: reader }, children)
18
+ }
19
+
20
+ /**
21
+ * The content of the provider's locale: `text(key, initial)` gives the HTML of a text
22
+ * and `image(key, initial)` an image. Where there is no value, what the code says.
23
+ * @returns {ContentReader}
24
+ */
25
+ export function useContent() {
26
+ return useContext(ContentContext)
27
+ }
@@ -0,0 +1,35 @@
1
+ import { createElement } from 'react'
2
+ import { EDITABLE_ATTRIBUTE, MAX_ATTRIBUTE, sanitizeText } from '@cms-93/core'
3
+ import { useContent } from './CmsProvider.js'
4
+
5
+ /**
6
+ * @typedef {object} EditableProps
7
+ * @property {string} name The content key, such as `home.title`.
8
+ * @property {string} [as] The element, `span` by default: `h1`, `p`, `a`…
9
+ * @property {number} [max] Maximum number of characters (`data-editable-max`).
10
+ * @property {import('react').ReactNode} [children] What the text says until it is edited: plain text.
11
+ */
12
+
13
+ /**
14
+ * An editable text. It shows the content of its key or, without it, its children.
15
+ *
16
+ * The text is set as HTML (it may have `<strong>` and `<em>`), so React leaves the element's
17
+ * inside alone while its value doesn't change: in the editor, what is typed stays.
18
+ * Plain text children work the same way. Other children (`<strong>` in JSX) are shown as
19
+ * they are until the text has a value, and then React may lose track of them if it re-renders.
20
+ * @param {EditableProps & Record<string, unknown>} props The rest go to the element.
21
+ */
22
+ export function Editable({ name, as = 'span', max, children, ...rest }) {
23
+ const value = useContent().text(name, typeof children === 'string' ? sanitizeText(escapeHtml(children)) : undefined)
24
+ const props = { ...rest, [EDITABLE_ATTRIBUTE]: name, ...(max === undefined ? {} : { [MAX_ATTRIBUTE]: max }) }
25
+ if (value === undefined) return createElement(as, props, children)
26
+ return createElement(as, { ...props, dangerouslySetInnerHTML: { __html: value } })
27
+ }
28
+
29
+ /**
30
+ * @param {string} text
31
+ * @returns {string}
32
+ */
33
+ function escapeHtml(text) {
34
+ return text.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;')
35
+ }
@@ -0,0 +1,34 @@
1
+ import { createElement } from 'react'
2
+ import { EDITABLE_ATTRIBUTE, RATIO_ATTRIBUTE, imageStyle } from '@cms-93/core'
3
+ import { useContent } from './CmsProvider.js'
4
+
5
+ /**
6
+ * @typedef {object} EditableImageProps
7
+ * @property {string} name The content key, such as `home.photo`.
8
+ * @property {string} src The image until it is changed.
9
+ * @property {string} [alt] Its alternative text until it is changed.
10
+ * @property {string | number} [ratio] The proportion it is cropped to (`data-editable-ratio`), such as `'4/5'`.
11
+ * @property {string} [srcSet] Only while it shows its own `src`: the browser would keep showing it instead of a new image.
12
+ * @property {string} [sizes] The same as `srcSet`.
13
+ * @property {import('react').CSSProperties} [style]
14
+ */
15
+
16
+ /**
17
+ * An editable `<img>`. It shows the image of its key (its file, alternative text, focal
18
+ * point and fit) or, without it, its own `src` and `alt`. Width, height and class stay.
19
+ * @param {EditableImageProps & Record<string, unknown>} props The rest go to the `<img>`.
20
+ */
21
+ export function EditableImage({ name, src, alt, ratio, srcSet, sizes, style, ...rest }) {
22
+ const image = useContent().image(name, { src, alt })
23
+ const ownFile = image.src === src
24
+ return createElement('img', {
25
+ ...rest,
26
+ [EDITABLE_ATTRIBUTE]: name,
27
+ ...(ratio === undefined ? {} : { [RATIO_ATTRIBUTE]: String(ratio) }),
28
+ src: image.src,
29
+ alt: image.alt ?? '',
30
+ srcSet: ownFile ? srcSet : undefined,
31
+ sizes: ownFile ? sizes : undefined,
32
+ style: { ...style, ...imageStyle(image) },
33
+ })
34
+ }
package/src/index.js ADDED
@@ -0,0 +1,6 @@
1
+ export { CmsProvider, useContent } from './CmsProvider.js'
2
+ export { Editable } from './Editable.js'
3
+ export { EditableImage } from './EditableImage.js'
4
+
5
+ /** @typedef {import('./Editable.js').EditableProps} EditableProps */
6
+ /** @typedef {import('./EditableImage.js').EditableImageProps} EditableImageProps */