@cms-93/astro 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,39 @@
1
- # Temporary Holding Version
1
+ # @cms-93/astro
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
+ Astro adapter: the website reads its content from cms-93 at build time. Needs Astro 5 or later.
6
+
7
+ License: MIT (see `LICENSE`).
8
+
9
+ ```js
10
+ // astro.config.mjs
11
+ import { defineConfig } from 'astro/config'
12
+ import { cms93 } from '@cms-93/astro'
13
+
14
+ export default defineConfig({
15
+ integrations: [cms93()],
16
+ })
17
+ ```
18
+
19
+ ```astro
20
+ ---
21
+ import { getContent, editableImage } from '@cms-93/astro'
22
+
23
+ const cms = await getContent(Astro.currentLocale ?? 'es')
24
+ ---
25
+ <h1 data-editable="home.title" data-editable-max="60" set:html={cms.text('home.title', 'Design that leaves a mark')} />
26
+ <img {...editableImage(cms, 'home.photo', { src: '/team.jpg', alt: 'The team', ratio: '4/5' })} width="800" />
27
+ ```
28
+
29
+ ## What it does
30
+
31
+ - **In development and in `astro preview`**, `/admin`, `/api` and `/media` go to the cms-93 server (`http://127.0.0.1:3093` by default), through the plugin of `@cms-93/vite`.
32
+ - **`getContent(locale)`** gives the content of the website in a page's language: `text(key, initial)` is the HTML of a text (with `set:html`) and `image(key, initial)` an image. Without a value, what the code says.
33
+ - **When the website is built**, the content is read once from `CMS_URL`: the address of the cms-93 server, or of the website that passes `/api` to it. A build that can't read it fails. Without `CMS_URL`, the website is built with its HTML, and the build says so.
34
+ - **In development**, on every page: what the editor saves shows on reloading. If the server is off, the website shows its HTML.
35
+ - **`editableImage(cms, key, attributes)`** gives the attributes of an editable `<img>`, to spread on it: 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.
36
+ - **`getContentDocument()`** gives the whole document, for React components in the page: `<CmsProvider content={…}>` of `@cms-93/react`.
37
+ - **Every page gets the edit mode script** (see `@cms-93/client`), so its CSS can stop animations with `html[data-cms-editing]`.
38
+
39
+ The options are those of `@cms-93/vite`: `server` and `contentUrl`.
package/package.json CHANGED
@@ -1,6 +1,25 @@
1
1
  {
2
2
  "name": "@cms-93/astro",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.0.1",
4
+ "description": "Astro adapter: the website reads its content from cms-93 at build time.",
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/client": "0.0.1",
19
+ "@cms-93/core": "0.0.1",
20
+ "@cms-93/vite": "0.0.1"
21
+ },
22
+ "scripts": {
23
+ "test": "node --test"
24
+ }
6
25
  }
@@ -0,0 +1,61 @@
1
+ import { loadContent } from '@cms-93/vite'
2
+
3
+ /** @typedef {import('@cms-93/core').ContentDocument} ContentDocument */
4
+ /** @typedef {import('@cms-93/vite').CmsOptions} CmsOptions */
5
+
6
+ /**
7
+ * Where the pages read the content from, set by the integration when Astro starts. It is
8
+ * kept on `globalThis` because Astro may load this package twice: once for its config and
9
+ * once for the pages.
10
+ * @typedef {object} ContentSource
11
+ * @property {'dev' | 'build'} mode
12
+ * @property {string} server The cms-93 server in development.
13
+ * @property {string | null} contentUrl Where the build reads the content.
14
+ * @property {Promise<ContentDocument | null>} [built] The content of the build, read once.
15
+ */
16
+
17
+ const SOURCE = Symbol.for('cms-93.astro.source')
18
+
19
+ /** @param {ContentSource} source */
20
+ export function setContentSource(source) {
21
+ /** @type {any} */ (globalThis)[SOURCE] = source
22
+ }
23
+
24
+ /** @returns {ContentSource | undefined} */
25
+ function getContentSource() {
26
+ return /** @type {any} */ (globalThis)[SOURCE]
27
+ }
28
+
29
+ /**
30
+ * The content document. In development, read on every page, so what the editor saves shows
31
+ * on reloading; if the server is off, the website shows its HTML. In the build, read once,
32
+ * and a build that can't read it fails. Without the integration, `null`.
33
+ * @param {{ request?: typeof fetch, warn?: (message: string) => void }} [options]
34
+ * @returns {Promise<ContentDocument | null>}
35
+ */
36
+ export function readContentDocument({ request, warn = console.warn } = {}) {
37
+ const source = getContentSource()
38
+ if (!source) {
39
+ warn('cms-93: add the integration to astro.config (integrations: [cms93()]). The website shows its HTML.')
40
+ return Promise.resolve(null)
41
+ }
42
+ if (source.mode === 'dev') {
43
+ return loadContent(source.server, { request }).catch((error) => {
44
+ warn(`${error.message} The website shows its HTML.`)
45
+ return null
46
+ })
47
+ }
48
+ source.built ??= readForBuild(source, { request, warn })
49
+ return source.built
50
+ }
51
+
52
+ /**
53
+ * @param {ContentSource} source
54
+ * @param {{ request?: typeof fetch, warn: (message: string) => void }} options
55
+ * @returns {Promise<ContentDocument | null>}
56
+ */
57
+ async function readForBuild({ contentUrl }, { request, warn }) {
58
+ if (contentUrl) return loadContent(contentUrl, { request })
59
+ warn('cms-93: CMS_URL is not set, so the website is built with its HTML as it is, without the content of cms-93.')
60
+ return null
61
+ }
@@ -0,0 +1,37 @@
1
+ import { EDITABLE_ATTRIBUTE, RATIO_ATTRIBUTE, imageStyle } from '@cms-93/core'
2
+
3
+ /** @typedef {import('@cms-93/core').ContentReader} ContentReader */
4
+
5
+ /**
6
+ * The attributes of an editable `<img>`, to spread on it: its file, alternative text, focal
7
+ * point and fit from the content, or its own `src` and `alt` without it. Its `srcset` and
8
+ * `sizes` stay only while it shows its own file.
9
+ *
10
+ * ```astro
11
+ * <img {...editableImage(cms, 'home.photo', { src: '/team.jpg', alt: 'The team', ratio: '4/5' })} width="800" />
12
+ * ```
13
+ * @param {ContentReader} cms
14
+ * @param {string} name The content key.
15
+ * @param {{ src: string, alt?: string, ratio?: string | number, srcset?: string, sizes?: string, style?: string }} attributes
16
+ * @returns {Record<string, string>}
17
+ */
18
+ export function editableImage(cms, name, { src, alt, ratio, srcset, sizes, style }) {
19
+ const image = cms.image(name, { src, alt })
20
+ const ownFile = image.src === src
21
+ /** @type {Record<string, string>} */
22
+ const result = { [EDITABLE_ATTRIBUTE]: name, src: image.src ?? src, alt: image.alt ?? '' }
23
+ if (ratio !== undefined) result[RATIO_ATTRIBUTE] = String(ratio)
24
+ if (ownFile && srcset) result.srcset = srcset
25
+ if (ownFile && sizes) result.sizes = sizes
26
+ const css = [style, toCss(imageStyle(image))].filter(Boolean).join(';')
27
+ if (css) result.style = css
28
+ return result
29
+ }
30
+
31
+ /**
32
+ * @param {{ objectPosition?: string, objectFit?: string }} style
33
+ * @returns {string}
34
+ */
35
+ function toCss({ objectPosition, objectFit }) {
36
+ return [objectPosition && `object-position:${objectPosition}`, objectFit && `object-fit:${objectFit}`].filter(Boolean).join(';')
37
+ }
@@ -0,0 +1,30 @@
1
+ import { createContentReader } from '@cms-93/core'
2
+ import { readContentDocument } from './contentSource.js'
3
+
4
+ /** @typedef {import('@cms-93/core').ContentReader} ContentReader */
5
+ /** @typedef {import('@cms-93/core').ContentDocument} ContentDocument */
6
+
7
+ /**
8
+ * The content of the website in a page's locale, to use in its frontmatter:
9
+ *
10
+ * ```astro
11
+ * ---
12
+ * const cms = await getContent(Astro.currentLocale ?? 'es')
13
+ * ---
14
+ * <h1 data-editable="home.title" set:html={cms.text('home.title', 'Design that leaves a mark')} />
15
+ * ```
16
+ * @param {string | null | undefined} locale The page's language. `es-ES` reads `es`, and one the website doesn't have reads its default locale.
17
+ * @returns {Promise<ContentReader>}
18
+ */
19
+ export async function getContent(locale) {
20
+ return createContentReader(await readContentDocument(), locale)
21
+ }
22
+
23
+ /**
24
+ * The whole content document, in every locale: for React components inside the page, with
25
+ * `<CmsProvider content={…}>` of `@cms-93/react`. `null` without content.
26
+ * @returns {Promise<ContentDocument | null>}
27
+ */
28
+ export function getContentDocument() {
29
+ return readContentDocument()
30
+ }
package/src/index.js ADDED
@@ -0,0 +1,3 @@
1
+ export { cms93, cms93 as default } from './integration.js'
2
+ export { getContent, getContentDocument } from './getContent.js'
3
+ export { editableImage } from './editableImage.js'
@@ -0,0 +1,28 @@
1
+ import { EDIT_MODE_SCRIPT } from '@cms-93/client'
2
+ import { cms93 as vitePlugin, resolveOptions } from '@cms-93/vite'
3
+ import { setContentSource } from './contentSource.js'
4
+
5
+ /** @typedef {import('@cms-93/vite').CmsOptions} CmsOptions */
6
+
7
+ /**
8
+ * The Astro integration of cms-93:
9
+ * - In development and in `astro preview`, /admin, /api and /media go to the cms-93 server.
10
+ * - Pages read their content with `getContent()`: when the website is built (from `CMS_URL`),
11
+ * and on every page in development.
12
+ * - Every page gets the script that marks edit mode before anything runs.
13
+ * @param {CmsOptions} [options]
14
+ * @returns {import('astro').AstroIntegration}
15
+ */
16
+ export function cms93(options) {
17
+ const resolved = resolveOptions(options)
18
+ return {
19
+ name: '@cms-93/astro',
20
+ hooks: {
21
+ 'astro:config:setup': ({ command, updateConfig, injectScript }) => {
22
+ setContentSource({ mode: command === 'dev' ? 'dev' : 'build', ...resolved })
23
+ updateConfig({ vite: { plugins: [vitePlugin(resolved)] } })
24
+ injectScript('head-inline', EDIT_MODE_SCRIPT)
25
+ },
26
+ },
27
+ }
28
+ }