@relyio/sdk 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,177 @@
 # @relyio/sdk
 
+## 0.13.0
+
+### Minor Changes
+
+- e678fb8: **`update()` and `restore()` say which entry links they left pointing nowhere.** `update()` returns the entry with `_metadata.brokenLinks`: each link another entry publishes whose anchor names a heading the revision took away, empty when it took none. `restore()` returns `_metadata.brokenLinks` beside `_metadata.leftOut`, both now in its type. A batch revision (`PATCH`, `PUT`) answers the same list under `data._metadata.brokenLinks`, with `returnData` or without, and a request retried with the same `Idempotency-Key` answers the list the first attempt did.
+- c2fe14d: **Filter by a reference inside blocks and rich text.** A typed client's `where()` and `fetchFirst()` accept a reference inside a list, a page builder or an object (`'sections.features'`) and a rich-text field that links to entries or declares a block holding a reference, each compared with an entry id: "pages that feature X". `$eq`/`$in` match an entry where some block holds it, `$ne`/`$nin` one where no block does, and `$isNull` asks whether any block holds a reference at all. Any other value inside a block, and a `json` field, is refused by name.
+- c2fe14d: **Heading anchors are unique per entry.** Headings are numbered across an entry's top-level rich-text fields in the order its type declares them, so `intro`'s "Overview" is `#overview` and `body`'s is `#overview-1`. `entryHeadingAnchors(entry)` computes an entry's anchors once; hand them to `<RichText anchors={…}>`, `renderRichText` or `richTextToHtml` (`anchors` option) and every field writes the ids an entry link's anchor names. A field rendered without `anchors` numbers its own headings, as before. A publish that takes away a heading other entries link to still lands, and the Content API's update answer lists the links it left pointing nowhere in `_metadata.brokenLinks`.
+- 39ea8c6: **A `json` field holds data nobody models.** `fields.json('chart', { config: { schema } })` declares a field whose value is any JSON value — an object, an array, a string, a number, a boolean or `null` — held to an optional JSON Schema on every write, a draft's included: a value the schema refuses is refused (`JSON_INVALID`), never stored. A read is typed by the schema — `type`, `properties`, `required`, `additionalProperties`, `items`, `enum`, `const`, `anyOf` and `oneOf` — and is `JsonValue` without one, never `any`:
+
+  ```ts
+  fields.json('chart', {
+    config: {
+      schema: {
+        type: 'object',
+        properties: { points: { type: 'array', items: { type: 'number' } } },
+        required: ['points'],
+      } as const,
+    },
+  })
+  // a read of `chart`: { points: number[] }
+  ```
+
+  Write the schema `as const` so `required`, `enum` and `const` keep their literals; `relyio generate-types` writes it so, and its Python target writes the same subset inline. A `json` field takes no `defaultValue`, and is neither searched nor filterable. The schema-modelling skill names the kind and when to reach for it.
+
+- c2d8071: **A preview can take an editor from any block to that block.** `relyioField` binds a value inside a field by its key path — `relyioField(page, 'sections[_key=="f2k6ub9s"].heading')` — the spelling a refused write already names a value by, and continues a binding it returned: `relyioField(binding, 'heading')` binds a field below it, `relyioField(binding, item)` an item of the list it binds. The attributes are the same five, version 1. `formatKeyPath` writes a key path and `parseKeyPath` reads one back, refusing an index, which names another item once a list is reordered.
+
+  `<Blocks>` and `<RichText>` take the field's binding as `field` and stamp each block, and each declared block and inline element, with its key path, on the element its component returns:
+
+  ```tsx
+  <Blocks
+    value={page.sections ?? []}
+    field={relyioField(page, 'sections')}
+    components={{
+      hero: (block, field) => (
+        <header>
+          <h1 {...relyioField(field, 'headline')}>{block.headline}</h1>
+          <RichText
+            value={block.body}
+            field={relyioField(field, 'body')}
+            components={{ callout: Callout }}
+          />
+        </header>
+      ),
+    }}
+  />
+  ```
+
+  Each component is handed its block's binding — a `<Blocks>` component as its second argument, a declared component as `field` — so a block inside a block carries its full path, `sections[_key=="f2k6ub9s"].body[_key=="c1"]`. A component that returns a fragment or an element of a component of its own spreads its binding itself. With no `field`, nothing is stamped and the markup is unchanged. The preview toolbar badges each stamped block and links it to its place in the Studio.
+
+- e0b742d: **`richTextToHtml` stamps each declared block with its key path, as `<RichText>` does.** Handed the field's binding as `field`, each declared Block and Inline element's writer is handed that node's binding as its second argument, and the one element it returns carries it — `data-relyio-field="body[_key==&quot;c1&quot;]"` after the element's own attributes — so a site rendering HTML without React still lets the preview toolbar take an editor from a block to the Studio:
+
+  ```ts
+  richTextToHtml(post.body, {
+    field: relyioField(post, 'body'),
+    declared: {
+      callout: (block, field) =>
+        `<aside>${richTextToHtml(block.body, { field: relyioField(field, 'body') })}</aside>`,
+    },
+  })
+  ```
+
+  A writer that returns text, several elements or an element it bound itself is written as it returns it; it holds the binding to write where it belongs. With no `field`, nothing is stamped and every writer is handed `undefined`.
+
+- 6f0ea50: **Rich text comes in and goes out as RelyIO Markdown: `@relyio/sdk/markdown`.** `richTextFromMarkdown(markdown)` reads a Markdown file into the rich-text tree, every node keyed and ready to write; `richTextToRelyIOMarkdown(value)` writes any rich-text value back as the same Markdown, and importing it again gives the same tree, keys aside. RelyIO Markdown is CommonMark with GitHub's tables, task lists and strikethrough, and directives for what Markdown has no syntax for — declared blocks and inline elements, entry links, code tabs, underline, highlight, sub- and superscript.
+
+  ```ts
+  import { richTextFromMarkdown, richTextToRelyIOMarkdown } from '@relyio/sdk/markdown'
+
+  const body = richTextFromMarkdown(await readFile('getting-started.md', 'utf8'))
+  await relyio.content('docPage').create({ title: 'Getting started', body })
+
+  richTextToRelyIOMarkdown(page.body) // the same Markdown, ready to edit and import again
+  ```
+
+  Markdown the tree cannot hold — HTML, an image, a footnote, a link's title — throws `RichTextMarkdownImportError`, whose `unplaced` names each one with its line and column; `readRichTextMarkdown` returns the tree and that list instead of throwing. A `table` or `code` field takes one block: `richTextFieldBlockFromMarkdown(markdown, 'table')` or `'codeGroup'`. Export throws `RichTextMarkdownExportError` for a node it cannot name. The parser has its own entry point, so a page that only renders rich text never loads it; `richTextToMarkdown` on the root, which writes plain Markdown and drops what it cannot hold, is unchanged.
+
+- 9873ca5: **A typed `where` takes what the API filters by everywhere it is offered, and an expanded singleton is typed as it is served.** `useEntries` and `relyioQueryOptions().entries()` take the `where` `client.content(type).query().where()` takes, so an object's field, a reference inside a block and `$isNull` compile there, and a `json` field or a whole list or object does not. A typed `asset(type)` client's `where()` and `fetchFirst()` are held to the same paths. `WhereOperator` gains `$inTheLast` and `$inTheNext` (`{ amount, unit }`), which a typed read offers on a `date` or `dateTime` field only, as the API asks them of nothing else. `children(id)` no longer takes `depth`: the route lists a parent's direct children, and refused every request that sent one with `400`; a nested tree is a list or entry read's `children()`. A singleton an include expands carries an entry's `_metadata` (`EntryMetadata`), not `SingletonMetadata`, and is typed so — in Python as `Expanded<Name>`, which a reference to the singleton now names.
+- 6c3d471: **A typed `where()` takes exactly what the API filters by.** `where()`, `fetchFirst()` and `fetch({ where })` name a field inside an object by its path — `{ 'pricing.basePrice': { $gte: 100 } }` — and take `$isNull` on any path. A condition the API refuses no longer compiles: a `json` field or a key inside one; a list, an object, a table or code as a whole; rich text that can point at no entry; and a reference or rich text a shared list translates item by item. `$regex`, which the API never read, is gone from `WhereOperator`. `fields.reference`, `fields.richText`, `fields.list` and `fields.object` keep the `localization` they were written with in their type, which is how a typed `where` tells a list translated whole from one translated item by item.
+
+### Patch Changes
+
+- 9ccfff0: **Filter by a reference or rich text a shared list translates item by item.** A typed client's `where()` now accepts these paths (`'sections.logo'` where each section's logo is translated): each item is matched in the read's locale by its own translation, or by that item's fallback, as the read shows it.
+- c2fe14d: **A slug may have segments.** `guide/schema/text-fields` is a valid slug; a leading, trailing or doubled slash is refused, naming which. Read an entry by such a slug with the slug encoded in the path (`guide%2Fschema%2Ftext-fields`), as the SDK already does.
+
+## 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