docs:Improve 0.18 blog post

Author: ntucker

website/blog/2026-04-24-v0.18-scalar-typed-downloads.md

@@ -3,11 +3,12 @@ title: 'v0.18: Scalar, Typed File Downloads, Filter-aware Collections'
 description: Lens-dependent entity fields with Scalar, typed file downloads via RestEndpoint content, automatic binary handling, and resource() nonFilterArgumentKeys for sort-aware collections
 authors: [ntucker]
 tags: [releases, rest, schema, endpoint, collection]
-draft: true
 ---
 
 import ScalarDemo from '../../docs/rest/shared/\_ScalarDemo.mdx';
 
+v0.18 focuses on richer data modeling for values that vary by request context, simpler typed downloads, and collection matching that better reflects real API filters.
+
 **New Features:**
 
 - [Scalar schema](/blog/2026/04/24/v0.18-scalar-typed-downloads#scalar) - Lens-dependent entity fields (e.g. portfolio-specific values) without ever mutating the underlying entity
@@ -17,8 +18,12 @@ import ScalarDemo from '../../docs/rest/shared/\_ScalarDemo.mdx';
 **Other Improvements:**
 
 - [Binary Content-Type auto-detection](/blog/2026/04/24/v0.18-scalar-typed-downloads#binary-auto-detection) - Images, PDFs, and other binary responses are handled automatically with no configuration ([#3868](https://github.com/reactive/data-client/pull/3868))
-- [Collection extender body types match HTTP method semantics](/rest/api/Collection) - PATCH extenders (`.move`, `.remove`) accept partial bodies; standalone `RestEndpoint` derives a typed body from the Collection's entity schema ([#3910](https://github.com/reactive/data-client/pull/3910))
-- Export [`CollectionOptions`](/rest/api/Collection) from `@data-client/endpoint` and `@data-client/rest` for typed Collection construction ([#3904](https://github.com/reactive/data-client/pull/3904))
+- [Collection extender body types match HTTP method semantics](/rest/api/Collection) - PATCH extenders (`.move`, `.remove`) accept partial bodies; standalone [RestEndpoint](/rest/api/RestEndpoint) derives a typed body from the [Collection](/rest/api/Collection)'s entity schema ([#3910](https://github.com/reactive/data-client/pull/3910))
+- Export [`CollectionOptions`](/rest/api/Collection) from `@data-client/endpoint` and `@data-client/rest` for typed [Collection](/rest/api/Collection) construction ([#3904](https://github.com/reactive/data-client/pull/3904))
+
+<ScalarDemo />
+
+The example shows the same `Company` entities rendered through different portfolio lenses. Stable [Entity](/rest/api/Entity) fields are reused, while lens-dependent values are selected from separate [`Scalar`](/rest/api/Scalar) cells.
 
 **[Breaking Changes:](/blog/2026/04/24/v0.18-scalar-typed-downloads#migration-guide)**
 
@@ -39,21 +44,19 @@ import SkillTabs from '@site/src/components/SkillTabs';
 
 ## Scalar {#scalar}
 
-[Scalar](/rest/api/Scalar) handles entity fields whose values depend on a runtime "lens" — like the
+[Scalar](/rest/api/Scalar) handles [Entity](/rest/api/Entity) fields whose values depend on a runtime "lens" — like the
 selected portfolio, currency, or locale. Multiple components can render the **same** entity through
 different lenses simultaneously, each seeing the correct values, while the entity itself never
 changes. Lens-dependent values live in a separate cell table and are joined at denormalize time
 from endpoint args.
 
-<ScalarDemo />
-
 `name` and `price` references stay stable across portfolio switches because the `Company` entity
-itself never changes — only the `Scalar` cell selected by the current lens does. A single `Scalar`
-instance can serve both as an `Entity.schema` field (parent entity inferred from the visit) and
+itself never changes — only the [`Scalar`](/rest/api/Scalar) cell selected by the current lens does. A single [`Scalar`](/rest/api/Scalar)
+instance can serve both as an [`Entity.schema`](/rest/api/Entity#schema) field (parent entity inferred from the visit) and
 standalone inside [`Values`](/rest/api/Values), [`[Scalar]`](/rest/api/Array),
 or [`Collection([Scalar])`](/rest/api/Collection) for cheap column-only refreshes (entity bound
-explicitly via `entity`). Cell pks are derived from the map key or via
-[`Scalar.entityPk()`](/rest/api/Scalar#entityPk), which defaults to `Entity.pk()` so custom and
+explicitly via [`entity`](/rest/api/Scalar#entity)). Cell pks are derived from the map key or via
+[`Scalar.entityPk()`](/rest/api/Scalar#entityPk), which defaults to [`Entity.pk()`](/rest/api/Entity#pk) so custom and
 composite primary keys work without an override.
 
 The normalized store keeps the entity stable and the lens cells separate:
@@ -70,11 +73,11 @@ entities['Scalar(portfolio)']['Company|1|A'] = { pct_equity: 0.50, shares: 10000
 entities['Scalar(portfolio)']['Company|1|B'] = { pct_equity: 0.30, shares: 6000 }
 ```
 
-The demo above pairs `getCompanies` with a cheap `getPortfolioColumns` lens-only refresh writing
+The demo pairs `getCompanies` with a cheap `getPortfolioColumns` lens-only refresh writing
 to the same cell table — see the [Scalar documentation](/rest/api/Scalar) for a full walkthrough
 of the caching behavior.
 
-`Scalar` also implements [queryKey](/rest/api/Scalar#queryKey) so it participates directly in
+[`Scalar`](/rest/api/Scalar) also implements [queryKey](/rest/api/Scalar#queryKey) so it participates directly in
 [useQuery](/docs/api/useQuery), [Controller.get](/docs/api/Controller#get), and [schema.Query](/rest/api/Query) —
 the full [Queryable](/rest/api/schema#queryable) surface — enumerating its cells for the current lens.
 
@@ -113,7 +116,7 @@ Previously, file downloads required a verbose `parseResponse` override. Now it's
 Setting `content` to a non-JSON value enforces `schema: undefined` at the type level, since binary data cannot be
 normalized. A runtime check provides a clear error message if a normalizable schema is accidentally used.
 
-Works with `extend()` and subclasses:
+Works with [`extend()`](/rest/api/RestEndpoint#extend) and [subclasses](/rest/api/RestEndpoint#inheritance):
 
 ```typescript
 // Extend a JSON endpoint into a blob downloader
@@ -132,7 +135,7 @@ class BlobEndpoint<O extends RestGenerics = any> extends RestEndpoint<O> {
 
 ## resource() `nonFilterArgumentKeys` {#non-filter-argument-keys}
 
-[`nonFilterArgumentKeys`](/rest/api/Collection#nonfilterargumentkeys) lets [resource()](/rest/api/resource)
+[`nonFilterArgumentKeys`](/rest/api/Collection#nonFilterArgumentKeys) lets [resource()](/rest/api/resource)
 declare which argument keys are *not* used to filter the collection results — typically sort,
 pagination, or display options. Without it, every distinct sort or page args would create a separate
 [Collection](/rest/api/Collection) bucket, and newly created items wouldn't appear in lists with
@@ -157,7 +160,7 @@ const PostResource = resource({
 });
 ```
 
-Now `group` and `author` are filter keys (they bucket separate Collections), but `orderBy` is
+Now `group` and `author` are filter keys (they bucket separate [Collections](/rest/api/Collection)), but `orderBy` is
 shared — `PostResource.getList.push()` adds the new post to *all* `orderBy` variants of a given
 `{ group, author }` bucket.
 
@@ -167,7 +170,7 @@ Accepts a `string[]`, `RegExp`, or predicate function:
 nonFilterArgumentKeys: /^(orderBy|page|cursor)$/,
 ```
 
-[#3914](https://github.com/reactive/data-client/pull/3914) - [`nonFilterArgumentKeys` docs](/rest/api/Collection#nonfilterargumentkeys)
+[#3914](https://github.com/reactive/data-client/pull/3914) - [`nonFilterArgumentKeys` docs](/rest/api/Collection#nonFilterArgumentKeys)
 
 ## Binary Content-Type auto-detection {#binary-auto-detection}
 
@@ -197,15 +200,21 @@ This upgrade requires updating all package versions simultaneously.
 <PkgTabs pkgs="@data-client/react@^0.18.0 @data-client/rest@^0.18.0 @data-client/endpoint@^0.18.0 @data-client/core@^0.18.0 @data-client/vue@^0.18.0 @data-client/test@^0.18.0 @data-client/img@^0.18.0" upgrade />
 
 The breaking changes in this release affect only **custom [Schema](/rest/api/CustomSchema) implementations**.
-If you only use built-in schemas (`Entity`, `resource()`, `Collection`, `Union`, `Values`, `Array`,
-`Object`, `Query`, `Invalidate`, `Lazy`, `Scalar`), the upgrade is drop-in. Otherwise, run the
-codemod from the [hero](#scalar) above to migrate custom schemas, then read on for the manual cases.
+If you only use [`resource()`](/rest/api/resource) and built-in schemas ([`Entity`](/rest/api/Entity),
+[`Collection`](/rest/api/Collection), [`Union`](/rest/api/Union), [`Values`](/rest/api/Values),
+[`Array`](/rest/api/Array), [`Object`](/rest/api/Object), [`Query`](/rest/api/Query),
+[`Invalidate`](/rest/api/Invalidate), [`Lazy`](/rest/api/Lazy), [`Scalar`](/rest/api/Scalar)), the upgrade is drop-in. Otherwise,
+run the codemod to migrate custom schemas, then read on for the manual cases:
+
+```bash
+npx jscodeshift -t https://dataclient.io/codemods/v0.18.js --extensions=ts,tsx,js,jsx src/
+```
 
 ### Schema.denormalize() takes a delegate {#denormalize-delegate}
 
 Skip this section if you don't implement custom [Schema](/rest/api/CustomSchema) classes.
 
-`Schema.denormalize()` is now `(input, delegate)` instead of the previous 3-parameter
+[`Schema.denormalize()`](/rest/api/CustomSchema) is now `(input, delegate)` instead of the previous 3-parameter
 `(input, args, unvisit)` signature. The new
 [`IDenormalizeDelegate`](/rest/api/CustomSchema) exposes `unvisit`, `args`, and a new `argsKey(fn)` helper.
 [#3887](https://github.com/reactive/data-client/pull/3887)
@@ -242,13 +251,13 @@ class Wrapper {
 
 The codemod handles class methods, object methods, function declarations, TypeScript interface
 signatures, and pass-through `someSchema.denormalize(input, args, unvisit)` calls. It also adds
-the `IDenormalizeDelegate` import as an inline `type` specifier on your existing
+the [`IDenormalizeDelegate`](/rest/api/CustomSchema) import as an inline `type` specifier on your existing
 `@data-client/*` import (or creates a new `import type` line if none is found).
 
 #### args-dependent output
 
-Reading `delegate.args` directly does **not** contribute to memoization. If your schema's *output*
-depends on those args (e.g. a lens), declare the dependency through `delegate.argsKey(fn)` so the
+Reading [`delegate.args`](/rest/api/CustomSchema) directly does **not** contribute to memoization. If your schema's *output*
+depends on those args (e.g. a lens), declare the dependency through [`delegate.argsKey(fn)`](/rest/api/CustomSchema) so the
 cache buckets correctly. The codemod cannot infer this — update by hand.
 
 `argsKey` returns `fn(args)` for convenience, and the function reference doubles as the cache path
@@ -291,8 +300,8 @@ AI-assisted migration is also available:
 
 Skip this section if you don't implement custom [Schema](/rest/api/CustomSchema) classes.
 
-`Schema.normalize()` now reads endpoint args and the recursive visitor from
-[`INormalizeDelegate`](/rest/api/CustomSchema), matching the new denormalize delegate shape.
+[`Schema.normalize()`](/rest/api/CustomSchema) now reads endpoint args and the recursive visitor from
+[`INormalizeDelegate`](/rest/api/CustomSchema), matching the new [denormalize delegate](/rest/api/CustomSchema) shape.
 The previous signature was `(input, parent, key, args, visit, delegate, parentEntity?)`;
 the new signature is `(input, parent, key, delegate, parentEntity?)`.
 [#3934](https://github.com/reactive/data-client/pull/3934)
@@ -346,21 +355,21 @@ normalize(input, parent, key, delegate, parentEntity) {
 }
 ```
 
-`delegate.visit()` already carries the same args for recursive normalization, so nested
-schemas do not need args passed explicitly.
+[`delegate.visit()`](/rest/api/CustomSchema) already carries the same args for recursive normalization, so nested
+[schemas](/rest/api/schema) do not need args passed explicitly.
 
 #### Additive: `parentEntity` on normalize
 
-The normalize delegate's `visit()` callback internally tracks the nearest enclosing
-entity-like schema and forwards it to `Schema.normalize()` as the optional trailing
-`parentEntity` argument. New schemas can opt in to discover their containing entity
+The [normalize delegate](/rest/api/CustomSchema)'s `visit()` callback internally tracks the nearest enclosing
+entity-like schema and forwards it to [`Schema.normalize()`](/rest/api/CustomSchema) as the optional trailing
+`parentEntity` argument. New [schemas](/rest/api/schema) can opt in to discover their containing entity
 at normalize time (used internally by [Scalar](/rest/api/Scalar)).
 
 #### Optional: consolidate Collection definitions {#collection-consolidation}
 
-`Collection` can now use both [`argsKey`](/rest/api/Collection#argsKey) and
+[`Collection`](/rest/api/Collection) can now use both [`argsKey`](/rest/api/Collection#argsKey) and
 [`nestKey`](/rest/api/Collection#nestKey) on the same instance. As an optional
-cleanup, replace paired top-level and nested Collections with one shared
+cleanup, replace paired top-level and nested [Collections](/rest/api/Collection) with one shared
 definition:
 
 <DiffEditor>