@relyio/sdk 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,93 @@
 # @relyio/sdk
 
+## 0.12.0
+
+### Minor Changes
+
+- ec2d34d: **Include paths reach into structure, cross references and pick fields; a read is typed by them.** An include path names fields joined by dots, through lists, page builders, objects and references, and each hop across a reference is written out — nothing expands past where a path stops. Fields in parentheses are the only fields each expanded entry returns, beside its `_metadata`.
+
+  ```ts
+  const home = await relyio
+    .content('page')
+    .findById('home')
+    .include(['sections.features(name,slug)', 'sections.customers.logo', 'ogImage'])
+    .execute()
+  ```
+
+  A reference a path expands is typed as the entry — narrowed to the fields a path picked — and **every other reference is typed as its id**, where it was `string | <entry>` whatever the read included. A path that holds no reference does not compile, and the error names the paths that do. `include()` on `findById()`, `query()`, `singleton()`, `settings()` and an asset type, `{ include }` on `fetch`, `fetchOne` and `fetchOneWithTag`, and `@relyio/react`'s `useEntry`, `useEntries`, `useSingleton` and `relyioQueryOptions()` all take checked paths. Two `include()` calls now add up rather than the second replacing the first, and a `singleton()` or `settings()` read's `{ include }` adds to the paths `include()` named. An include list the compiler cannot see — a `string[]` — is taken as written and types every reference as either.
+
+- 8df140c: **A list's items take a fieldset: `fields.list(id, { config: { of } })`.** `of` names the fieldset each item takes, and every item holds that fieldset's fields plus two keys: `_type`, the fieldset's id (present even when the list allows one shape), and `_key`, the item's key, created when the item is inserted and kept for its life. `subfields` is gone, with no alias: a deploy that sends it is refused.
+
+  ```ts
+  const question = fieldset('question', {
+    displayName: 'Question',
+    fields: [
+      fields.shortText('question', { config: { required: true } }),
+      fields.richText('answer'),
+    ],
+  })
+
+  fields.list('faq', { config: { of: question } })
+  // a read types each item as { readonly _type: 'question'; readonly _key: string; question: string; answer?: string }
+  ```
+
+  In YAML, `of` names a fieldset declared under the top-level `fieldsets` (`of: question`), or declares one in place. `relyio generate-types` writes a list's `of` as a `fieldset(…)` call, and the Python target types each item with `type` and `key` beside its fields.
+
+- d2d4e94: **Rich text renders with no code: `<RichText>` in React, and HTML or plain Markdown anywhere.** `<RichText value={post.body} />` from `@relyio/react` renders every built-in — paragraphs, headings, quotes, bullet, numbered and task lists, code and code groups, tables, dividers, line breaks and every mark — and `components` replaces any of them, keyed by `_type` and typed by the built-in it replaces:
+
+  ```tsx
+  <RichText
+    value={post.body}
+    components={{
+      heading: ({ value, children }) => <Heading level={value.level}>{children}</Heading>,
+    }}
+  />
+  ```
+
+  `richTextToHtml(value)` from `@relyio/sdk` writes the exact markup `<RichText>` renders with no components, text and attributes escaped, with no DOM — for Node, a browser or a Worker. `richTextToMarkdown(value)` writes GitHub Flavored Markdown and drops what it cannot hold (underline, highlight, sub- and superscript, a code block's filename), keeping the text. A link to a scheme other than `http:`, `https:`, `mailto:` or `tel:` — `javascript:`, `data:` — renders its text with no anchor in all three. A node or mark from a newer RelyIO that this version does not know renders nothing, or its text, and never throws. All three share one walk, `renderRichText`, also exported for other frameworks; the functions are on `@relyio/sdk` and `@relyio/sdk/rich-text`.
+
+- a97ccc4: **Rich text is a tree, not HTML.** A `richText` field's value is `{ _type: 'richText', version: 1, children }`: paragraphs, headings, quotes, bullet, numbered and task lists whose items hold blocks, code blocks and code groups, tables, dividers and line breaks, with text runs carrying named marks. Every node but a text run carries `_type` and a `_key`. The SDK exports the tree's types (`RichTextValue` and each node's), types a read of a `richText` field by them, and types `RichTextConfig.defaultValue` as a tree. A field narrows what it allows with `structure`, `marks` and `multiline`; `allowedFormats` and `embedTypes` are gone. A write of an HTML string is refused.
+
+  **`_metadata.refs` names a reference inside structure by its include path** (`sections.customers`, `sections.media.image`), with no shape segment. **A url field takes a site-relative path** (`/sign-up`) as well as an absolute URL. **A multi reference takes `minItems` and `maxItems`.**
+
+  **A saved query's string includes are include paths**, read as `?include=` reads them (`sections.customers.logo`, `sections.features(name,slug)`); the forward object form and its type `IncludeSelection` are removed, and `{ relationship, … }` stays for reverse joins, filters and counts.
+
+- 60d416f: **A type's `fields` hold fields and fieldsets side by side, and a required field is always present.**
+
+  A fieldset among a type's fields is a section of the form: its fields are the record's own, so grouping the form never changes a read. The type-level `fieldsets` key is gone, with no alias. A fieldset id names one shape across the whole schema, so a deploy refuses two different shapes under one id, a fieldset that contains itself, and a field id used twice across a type's sections.
+
+  ```ts
+  const seo = fieldset('seo', {
+    displayName: 'SEO',
+    fields: [fields.shortText('metaTitle'), fields.boolean('noIndex')],
+  })
+
+  defineContentType('article', {
+    displayName: 'Article',
+    fields: [fields.shortText('title', { config: { required: true } }), seo],
+  })
+  // a read types an article as { title: string; metaTitle?: string; noIndex?: boolean }
+  ```
+
+  In YAML, declare a fieldset where it is used, or once under a top-level `fieldsets` and place it with `fieldset: <id>`.
+
+  A required field is present in every read's type. Text, lists, rich text and booleans may be empty in a draft: a draft read fills the kind's empty value and lists the field in `_metadata.emptyRequiredFields`. Numbers, dates, single choices and single references have no empty value, so they are required from creation: a create without them is refused, naming the fields, and a required single reference is never `null`.
+
+  `relyio validate` and `relyio deploy` answer with every error at once, including the checks that run past a field config the parse refuses.
+
+- b1fd6f6: **`table` and `code` fields hold exactly a rich-text table's and code group's value.** `fields.table('comparison')` and `fields.code('snippet', { config: { languages: ['typescript', 'bash'], maxTabs: 4 } })` declare a field whose value is one built-in of the rich-text tree — a read types it `RichTextTable` or `RichTextCodeGroup`, the very type of the same block inside a `richText` field — so a comparison table on a page and a table in a doc are one thing, and a value copied between them is accepted unchanged. A code group holds one tab or more, each a code block with its text and an optional `label`, `language`, `filename` and `lines`; `languages` makes every tab name one of them and `maxTabs` bounds the tabs. Neither has an empty value, so a required one is given when the entry is created.
+
+  `<RichText value={page.comparison} />`, `richTextToHtml` and `richTextToMarkdown` take a table or code field's value as they take a tree, and draw it as the same block — a replacement in `components` included:
+
+  ```tsx
+  <RichText
+    value={showcase.snippet}
+    components={{ codeGroup: ({ children }) => <Tabs>{children}</Tabs> }}
+  />
+  ```
+
+  `renderRichText` takes it too, and its input type is exported as `RichTextRenderable`. The schema-modelling skill names both kinds.
+
 ## 0.11.0
 
 ### Minor Changes