@relyio/sdk 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,140 @@
 # @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
+
+- 84f4acb: **A `dateTime` field reads back in UTC.** A `dateTime` is stored as its instant in UTC at millisecond precision, whatever offset it was written in, and every read returns it that way: write `2026-09-30T23:30:00-05:00` and you read back `2026-10-01T04:30:00.000Z`. The offset you sent is not kept. A `date` field is unchanged: `YYYY-MM-DD`.
+
+  Comparing two values is now comparing two instants, and a `where` on a date field compares the way you would expect across offsets:
+
+  - `{ dried: { $lt: '2026-10-01' } }` keeps the instants before the UTC day of 1 October. It used to compare text, so `2026-09-30T23:30:00-05:00` — which is 04:30 UTC on the 1st — was listed.
+  - A day compares with an instant's UTC day: `{ dried: { $lte: '2026-10-01' } }` keeps every instant of that day, and `{ dried: '2026-10-01' }` matches any of them.
+  - An instant you compare with is read with its offset: `{ dried: { $gte: '2026-10-01T06:30:00+02:00' } }` is 04:30 UTC.
+  - `$inTheLast` and `$inTheNext` on a `dateTime` or `date` field match, counted in UTC from the moment of the read. They matched nothing before.
+
+  A value that names no date — a word, or a time with no offset such as `2026-10-01T10:00` — is refused with `400 REQUEST_INVALID`, as is `$inTheLast` on a field that holds no date. If you compared a stored `dateTime` with the text you wrote, compare instants instead:
+
+  ```ts
+  const sameInstant = Date.parse(entry.dried) === Date.parse('2026-09-30T23:30:00-05:00')
+  ```
+
+- 8c5b215: **A change to shared fields is reported as `hasDraft`, not as the default locale's draft.** A read's `_metadata` reports unpublished work in two kinds, apart: `draftLocales` names the locales with unpublished edits of their own, and `hasDraft` says the shared (non-localized) fields have unpublished changes. Publishing any locale makes a shared change live, so it is pending in every locale, and no locale code is listed for it.
+
+  `draftLocales` used to list the default locale's code for a shared-field draft. It no longer does: an entry whose only pending change is a shared field now reads `draftLocales: []` with `hasDraft: true`, in every locale you read it in. A locale has unpublished work when `draftLocales` names it or `hasDraft` is `true`:
+
+  ```ts
+  const { draftLocales, hasDraft } = entry._metadata
+  const frenchHasPendingWork = hasDraft || draftLocales.includes('fr')
+  ```
+
+  A settings group's `_metadata` — on `GET /v1/settings/{groupId}` and on each written group of `GET /v1/settings` — now carries `hasDraft` too, as an entry's, a singleton's and a search hit's already did, and so does each entry a query returns. `LocalePublicationFields` includes it.
+
+- 4614003: **A view filter names its field as the Studio's entry list does.** A field your schema declares is `fields.<id>` — `fields.featured`, `fields.seo.title` for a component's sub-field — and a system field is `_metadata.<id>`: `_metadata.status`, `_metadata.createdAt`, `_metadata.updatedAt`, the name the Content API already gives those values in an entry's `_metadata`. A field called `status` and the entry's own lifecycle are now both filterable on one schema, where deploy used to refuse a filter on either:
+
+  ```ts
+  defineView('openTickets', {
+    name: 'Open tickets',
+    scope: { type: 'contentType', contentType: 'ticket' },
+    filters: [
+      { field: 'fields.status', operator: 'is', value: 'open' },
+      { field: '_metadata.status', operator: 'is', value: 'active' },
+    ],
+  })
+  ```
+
+  A filter on a bare field id — `{ field: 'featured', … }` — is refused at `relyio deploy` and `relyio status` as a field the view's entries cannot be filtered by, at `views.<n>.filters.<n>.field`. Write `fields.featured`. A YAML schema's `views[].filters` take the same names.
+
+  **A view's `sort` names its field the same way**, because the Studio puts a view's order in the entries read beside its filters: `sort: { field: '_metadata.updatedAt', direction: 'desc' }`, or `fields.title`. Deploy now refuses a sort whose field is a bare id, or one the view's entries cannot be sorted by (a long text, for example), at `views.<n>.sort.field`. A view's `columns` and `metadataFields` are display settings and still name field ids as written.
+
 ## 0.10.0
 
 ### Minor Changes