@wervt/cms 0.0.1 → 0.0.3

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.
Files changed (45) hide show
  1. package/README.md +136 -13
  2. package/dist/editor/assets/Button-BHCKwuIs.js +6 -0
  3. package/dist/editor/assets/RichTextInput-DHmilx6T.js +271 -0
  4. package/dist/editor/assets/Toast-pKrAdYOo.js +13 -0
  5. package/dist/editor/assets/index-JJD_O40W.js +16 -0
  6. package/dist/editor/assets/index-kXxO7vu1.css +2 -0
  7. package/dist/editor/assets/poppins-latin-400-normal-BOb3E3N0.woff +0 -0
  8. package/dist/editor/assets/poppins-latin-400-normal-cpxAROuN.woff2 +0 -0
  9. package/dist/editor/assets/poppins-latin-500-normal-C8OXljZJ.woff2 +0 -0
  10. package/dist/editor/assets/poppins-latin-500-normal-DGXqpDMm.woff +0 -0
  11. package/dist/editor/assets/poppins-latin-600-normal-BJdTmd5m.woff +0 -0
  12. package/dist/editor/assets/poppins-latin-600-normal-zEkxB9Mr.woff2 +0 -0
  13. package/dist/editor/index.html +15 -0
  14. package/dist/editor-theme.d.ts +28 -0
  15. package/dist/editor-theme.js +62 -0
  16. package/dist/module.d.ts +6 -1
  17. package/dist/module.js +97 -11
  18. package/dist/runtime/app/CmsRichText.d.ts +15 -0
  19. package/dist/runtime/app/CmsRichText.js +48 -0
  20. package/dist/runtime/app/useCms.d.ts +9 -2
  21. package/dist/runtime/app/useCms.js +11 -5
  22. package/dist/runtime/fields.d.ts +24 -0
  23. package/dist/runtime/fields.js +109 -0
  24. package/dist/runtime/pages.d.ts +3 -0
  25. package/dist/runtime/pages.js +14 -0
  26. package/dist/runtime/schema.d.ts +108 -0
  27. package/dist/runtime/schema.js +74 -0
  28. package/dist/runtime/server/access.js +1 -1
  29. package/dist/runtime/server/dev-images.d.ts +2 -0
  30. package/dist/runtime/server/dev-images.js +12 -0
  31. package/dist/runtime/server/editor.get.d.ts +2 -0
  32. package/dist/runtime/server/editor.get.js +9 -0
  33. package/dist/runtime/server/entry.get.d.ts +7 -2
  34. package/dist/runtime/server/entry.get.js +11 -1
  35. package/dist/runtime/server/entry.put.js +14 -1
  36. package/dist/runtime/server/images.d.ts +4 -0
  37. package/dist/runtime/server/images.js +30 -0
  38. package/dist/runtime/server/schema.get.d.ts +10 -0
  39. package/dist/runtime/server/schema.get.js +10 -0
  40. package/dist/runtime/server/sniff.d.ts +11 -0
  41. package/dist/runtime/server/sniff.js +53 -0
  42. package/dist/runtime/server/upload.post.d.ts +13 -0
  43. package/dist/runtime/server/upload.post.js +44 -0
  44. package/package.json +29 -5
  45. package/dist/runtime/app/editor.vue +0 -32
package/README.md CHANGED
@@ -1,7 +1,8 @@
1
1
  # @wervt/cms
2
2
 
3
- Editable texts for Nuxt sites on [wervt](https://wervt.app). Pages read their texts with
4
- `useCms`; the site's owner changes them on the live site, without a redeploy.
3
+ Editable texts, images and lists for Nuxt sites on [wervt](https://wervt.app). A page describes
4
+ what can be edited in `cms/`, reads it with `useCms`, and the site's owner changes it on the live
5
+ site, without a redeploy.
5
6
 
6
7
  ```sh
7
8
  pnpm add @wervt/cms @wervt/nuxt
@@ -9,22 +10,93 @@ pnpm add @wervt/cms @wervt/nuxt
9
10
 
10
11
  ```ts [nuxt.config.ts]
11
12
  export default defineNuxtConfig({
12
- modules: ['@wervt/cms'], // loads @wervt/nuxt with its database turned on
13
+ modules: ['@wervt/cms'], // loads @wervt/nuxt with its database and ablage for uploads
14
+ })
15
+ ```
16
+
17
+ ```ts [cms/home.ts]
18
+ import { defineCmsPage, image, list, text } from '@wervt/cms/schema'
19
+
20
+ export default defineCmsPage('home', {
21
+ hero: {
22
+ title: text('Welcome to Café Rosa'),
23
+ image: image('/hero.jpg', { label: 'Photo' }), // a file in public/
24
+ },
25
+ hours: list({ day: text(), time: text() }, [
26
+ { day: 'Mon–Fri', time: '8–18' },
27
+ { day: 'Sat', time: '9–14' },
28
+ ]),
13
29
  })
14
30
  ```
15
31
 
16
32
  ```vue [app/pages/index.vue]
17
33
  <script setup lang="ts">
18
- const home = useCms('home', { title: 'Welcome', hours: 'Mon–Fri 8–18' })
34
+ const home = useCms('home')
19
35
  </script>
20
36
 
21
37
  <template>
22
- <h1>{{ home.title }}</h1>
23
- <p>{{ home.hours }}</p>
38
+ <h1>{{ home.hero.title }}</h1>
39
+ <img
40
+ :src="home.hero.image.src"
41
+ :srcset="home.hero.image.srcset"
42
+ sizes="100vw"
43
+ :alt="home.hero.image.alt"
44
+ />
45
+ <ul>
46
+ <li v-for="row in home.hours" :key="row.day">{{ row.day }}: {{ row.time }}</li>
47
+ </ul>
24
48
  </template>
25
49
  ```
26
50
 
27
- The defaults render until an entry is saved, so a page works before anyone edits it.
51
+ `useCms('home')` is typed from `cms/home.ts`. Everything renders from the defaults until someone
52
+ saves, so a page works before anyone edits it. Pages must render on the server (no prerendering),
53
+ or edits only show after the next build.
54
+
55
+ ## Fields
56
+
57
+ | Field | The page gets | Notes |
58
+ | -------------------------- | ----------------------- | ---------------------------------------------------------- |
59
+ | `text('…')` | `string` | `{ multiline: true }` for several lines |
60
+ | `richText('…')` | `string` (Markdown) | shown with `<CmsRichText :value>` |
61
+ | `toggle(true)` | `boolean` | |
62
+ | `link({ label, href })` | `{ label, href }` | `href`: a path, `#…`, `https://`, `mailto:` or `tel:` |
63
+ | `image('/a.jpg')` | `{ src, srcset?, alt }` | always an image; `image()` without a default can be `null` |
64
+ | `list({ …fields }, [ … ])` | an array of items | saved as a whole; each item gets the fields' defaults |
65
+ | `{ …fields }` | an object | a group of fields shown together |
66
+
67
+ Every field takes `{ label }` for the editor. Keep field names and page keys stable: a renamed
68
+ field shows its default again (the old value is kept, but no longer shown).
69
+
70
+ Saved values that no longer fit a field (it changed from text to a list, say) are ignored and the
71
+ default shows, so changing `cms/` never breaks a page.
72
+
73
+ ## Rich text
74
+
75
+ A `richText` field holds Markdown: bold, italic, links, headings and lists, written in the editor
76
+ with a toolbar. Show it with the `CmsRichText` component, which renders it on the server and
77
+ hydrates like any component (Comark's parser comes along in the page's JavaScript):
78
+
79
+ ```vue
80
+ <CmsRichText :value="home.intro" />
81
+ ```
82
+
83
+ Editors may type anything, so `CmsRichText` keeps raw HTML, `{style=…}` attributes, Comark
84
+ components and `javascript:` or `data:` links as plain text. Rendering the Markdown yourself
85
+ skips that.
86
+
87
+ ## Images
88
+
89
+ Editors upload images at `POST /api/_cms/images` (`multipart/form-data`, field `file`): JPEG, PNG,
90
+ WebP, GIF, AVIF or HEIC (iPhone photos), up to 25 MB. The editor shrinks photos to 2400 px before
91
+ sending them.
92
+
93
+ - **Deployed**: the file goes to the app's bucket. The page gets a signed `src` in 1600 px and a
94
+ `srcset` from 640 to 2400 px, resized by wervt's image service.
95
+ - **`nuxt dev`**: the file goes to `public/cms/` (up to 5 MB, no HEIC) and is served as it is.
96
+ Commit it with `cms/entries.json`; the deploy ships both.
97
+
98
+ The stored value is `{ id }` for an upload or `{ src }` for a file the app ships with, plus an
99
+ optional `alt`. Saving what `GET` answered stores the same thing again.
28
100
 
29
101
  ## Where entries live
30
102
 
@@ -32,18 +104,31 @@ The defaults render until an entry is saved, so a page works before anyone edits
32
104
  - **Deployed**: saving writes the app's database. The module turns the database on, so the app
33
105
  needs no `drizzle/` folder for it; the table is created on first use.
34
106
  - When both have an entry for a key, the newer one wins. Editing `cms/entries.json` and
35
- deploying replaces a live edit; a later live edit wins again.
107
+ deploying replaces a live edit; a later live edit wins again. When you edit the file by hand,
108
+ leave out `updatedAt`: a missing time means "just changed".
36
109
 
37
110
  Keys are lowercase words joined by `-`, `_` or `/` (`home`, `menu/drinks`), up to 200
38
- characters.
111
+ characters. A key without a page in `cms/` holds any JSON object; `useCms('legacy', defaults)`
112
+ reads it with the saved fields over `defaults`.
39
113
 
40
114
  ## Editing
41
115
 
42
- `/_cms?key=<key>` is a small editor for one entry. `GET` and `PUT /api/_cms/entries/<key>` are
43
- the API behind it; reading is public, saving needs an editor.
116
+ The editor is at `/_cms` on the site: one form per page in `cms/`, made for phones too. Lists
117
+ can be reordered, images come from the camera or the gallery, and a page defined with
118
+ `{ label, path }` (`defineCmsPage('home', { … }, { label: 'Home', path: '/' })`) shows its label
119
+ and a button that opens it on the site. `/_cms?key=<key>` opens one page. It speaks English and German, after the browser's language.
120
+
121
+ The API behind it:
122
+
123
+ - `GET /api/_cms/entries/<key>`: the page's values, defaults filled in. Public.
124
+ - `PUT /api/_cms/entries/<key>`: saves; the body is the value. Checked against the page's
125
+ fields, with a `400` that names the field that doesn't fit.
126
+ - `GET /api/_cms/schema`: the pages and their fields. Public.
127
+ - `POST /api/_cms/images`: uploads an image (see above).
44
128
 
45
- The app's owner, members and wervt admins can edit. To let others edit, list their addresses
46
- (only confirmed ones count):
129
+ The app's owner, members and wervt admins can edit, once signed in at `/_wervt/login` (the
130
+ editor links there; in `nuxt dev` it signs you in as the owner). To let others edit, list their
131
+ addresses (only confirmed ones count):
47
132
 
48
133
  ```ts [nuxt.config.ts]
49
134
  export default defineNuxtConfig({
@@ -52,3 +137,41 @@ export default defineNuxtConfig({
52
137
  ```
53
138
 
54
139
  or set `NUXT_CMS_EDITORS` on the deployed app (`wervt env`), which needs no redeploy.
140
+
141
+ ## The editor's look
142
+
143
+ The editor looks like wervt's dashboard: Poppins, black and white, a blue accent, light or dark
144
+ after the device. To match a site, give it a theme; every value is plain CSS:
145
+
146
+ ```ts [nuxt.config.ts]
147
+ export default defineNuxtConfig({
148
+ cms: {
149
+ editor: {
150
+ theme: {
151
+ primary: { light: '#1475bd', dark: '#5ab0ea' }, // links, focus, toggles; or one color
152
+ buttons: 'primary', // the save button in the primary color instead of black and white
153
+ font: "'Inter', system-ui, sans-serif",
154
+ radius: '0.5rem',
155
+ stylesheet: '/cms-editor.css', // loaded after the editor's styles: @font-face and more
156
+ light: { bg: '#ffffff', 'bg-muted': '#f6f5f2', text: '#1c1b19', 'text-muted': '#57544e' },
157
+ dark: { bg: '#1a1a19', 'bg-muted': '#141413', text: '#edece9', 'text-muted': '#a5a29c' },
158
+ },
159
+ },
160
+ },
161
+ })
162
+ ```
163
+
164
+ `light` and `dark` take Nuxt UI's color tokens without `--ui-`: `bg`, `bg-muted` (fields),
165
+ `bg-elevated`, `bg-accented`, `bg-inverted`, `border`, `border-muted`, `border-accented`,
166
+ `border-inverted`, `text`, `text-dimmed`, `text-muted`, `text-toned`, `text-highlighted` and
167
+ `text-inverted` (text on primary buttons). The editor is its own page, so the site's fonts don't
168
+ reach it: a font other than the device's needs an `@font-face` in `stylesheet`, a file in the
169
+ site's `public/` or an `https://` URL. Values that would break out of CSS fail the build.
170
+
171
+ ## Developing the editor
172
+
173
+ The editor is a Vite app in `editor/`, built into the package (`vp build editor`, part of
174
+ `vp run build`). To work on it, run a site with the module, then
175
+ `CMS_SITE=http://localhost:3000 vp dev editor` in `packages/cms`: the editor comes from Vite at
176
+ `http://localhost:5173/_cms/`, its API and images from the site. The site's `cms.editor.theme` only
177
+ applies where the site serves the editor.