@datocms/product-scenes 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,93 @@
-# Temporary Holding Version
+# @datocms/product-scenes
 
-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.
+The pictures of the DatoCMS interface on www.datocms.com, made with the real components of the product and rendered to static HTML on the server.
+
+This package is for the DatoCMS website only. It has no support and no semver promise: any version can change the API. The licence does not let you use it in other projects.
+
+The package is a kit of parts: the frame (`Stage`), the parts of the screens of the cms (`NavigationBar`, `ContentSidebar`, `RecordEditorLayout`, `RecordForm`, `StructuredTextInput`, `InfoAside`) and a few components of the cms (`Button`, `InfoList`, `Pill`). The website composes the scenes from the parts and gives the fake data.
+
+## Install
+
+```bash
+npm install @datocms/product-scenes react@19 react-dom@19
+```
+
+The package has no dependencies: the build contains the components of the cms. React 19 is a peer dependency.
+
+## The CSS and the Fonts
+
+Import the CSS once, in the layout of the website:
+
+```ts
+import '@datocms/product-scenes/product-scenes.css';
+```
+
+Every rule of the file applies only inside a scene, thus the CSS of the page does not change. The file has no `@font-face` rule: the page gives the fonts that it already loads, with two custom properties on an element above the scenes.
+
+```css
+:root {
+  --product-scenes-font-sans: 'ABC Oracle', sans-serif;
+  --product-scenes-font-mono: 'Geist Mono', monospace;
+}
+```
+
+## A Scene
+
+```tsx
+import {
+  ContentSidebar,
+  InfoAside,
+  NavigationBar,
+  RecordEditorLayout,
+  RecordForm,
+  Stage,
+} from '@datocms/product-scenes';
+
+export function PostEditorScene({ scheme }: { scheme: 'light' | 'dark' }) {
+  return (
+    <Stage description="The record editor of DatoCMS, with a blog post." scheme={scheme}>
+      <RecordEditorLayout
+        navigationBar={<NavigationBar user={{ name: 'Demo User' }} />}
+        sidebar={
+          <ContentSidebar
+            items={[{ kind: 'model', id: 'posts', name: '📝 Posts', active: true }]}
+          />
+        }
+        aside={
+          <InfoAside>
+            <InfoAside.RecordInfo
+              id="Gd8Qnm7pRUKPjnCVhCYOZw"
+              status="draft"
+              createdAt="09/21/2025, 13:34"
+              updatedAt="09/21/2025, 15:39"
+              createdBy={{ name: 'Ronak Ganatra' }}
+            />
+          </InfoAside>
+        }
+      >
+        <RecordForm title="Hello world" icon="📝">
+          <RecordForm.Field label="Title" required>
+            <RecordForm.StringInput value="Hello world" large />
+          </RecordForm.Field>
+        </RecordForm>
+      </RecordEditorLayout>
+    </Stage>
+  );
+}
+```
+
+In an Astro page, render the scene as a component, without a `client:` directive:
+
+```astro
+<PostEditorScene scheme="light" />
+```
+
+A model or a folder of `ContentSidebar` and the `icon` of `RecordForm` use the emoji of the model as the icon, as in the cms. A part that shows another icon takes it as a `ReactNode`.
+
+## The Rules of a Scene
+
+- **No `client:` directive.** A scene is static HTML. The package sends no JS to the browser, and the parts do not work in the browser.
+- **Controlled inputs with constant values.** Give each input its value as a prop. Do not keep a state, and do not wait for a user action.
+- **No overlays and no portals.** Do not open a dropdown, a tooltip, a modal or a popover: there is no JS to place it. Show the closed state.
+- **Fixed dates and fixed data.** Write the dates as text. Do not read the clock and do not fetch, thus two renders give the same picture.
+- **One `Stage` for each scene, with a `description`.** The screen is hidden from assistive technology, thus the description is the only text that a screen reader hears. Write what the picture shows. A page can show many stages.