docs(record): add bilingual usage guides

2026-09-28 17:24:14 +08:00
parent d3de7cc172
commit 1353dc3145
9 changed files with 488 additions and 0 deletions
@@ -0,0 +1,28 @@
+---
+title: Overview
+description: Learn how the Record package exposes the current record in data-driven interfaces.
+order: 1
+toc:
+  - id: package-role
+    title: Package role
+  - id: capabilities
+    title: Capabilities
+  - id: design-boundary
+    title: Design boundary
+---
+
+## Package role {#package-role}
+
+`@workspace/record` is a UI-free React record context layer. A record is not restricted to an object: numbers, booleans, strings, arrays, functions, and plain objects are all valid; only `undefined` and `null` represent absence. Descendants can read the current value without passing a `record` prop through every level.
+
+## Capabilities {#capabilities}
+
+- Provide the current record with `RecordProvider`.
+- Read context with `useRecord`, or override it with an explicit record.
+- Read nested fields through typed dot paths with `useFieldValue`.
+- Create an isolated record context for each list item with `RecordsIterator`.
+- Make components work standalone and inside existing contexts with `OptionalRecordProvider`.
+
+## Design boundary {#design-boundary}
+
+This package does not fetch, cache, paginate, manage forms, or render UI. A data layer only needs to pass loaded values to a provider or iterator. `undefined` and `null` mean that no record is available; `0`, `false`, and an empty string remain valid records. Read live form edits from form state instead.