@timber-js/app 0.2.0-alpha.217 → 0.2.0-alpha.219

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. package/agent-skill.md +5 -5
  2. package/dist/_chunks/{actions-CUh3cClk.js → actions-BwkmAYXq.js} +8 -1
  3. package/dist/_chunks/actions-BwkmAYXq.js.map +1 -0
  4. package/dist/_chunks/cloudflare-Byxl8FWP.js.map +1 -1
  5. package/dist/_chunks/dev-server-B8zsT-ee.js.map +1 -1
  6. package/dist/_chunks/dist-DtrJyBbw.js.map +1 -1
  7. package/dist/_chunks/graph-cache-CYiUS2aS.js.map +1 -1
  8. package/dist/_chunks/use-query-states-I3JMng6J.js.map +1 -1
  9. package/dist/adapters/cloudflare.js +1 -2
  10. package/dist/adapters/nitro.js.map +1 -1
  11. package/dist/analyze/graph-command.js.map +1 -1
  12. package/dist/client/error-boundary.js +1 -2
  13. package/dist/client/form.d.ts +34 -37
  14. package/dist/client/form.d.ts.map +1 -1
  15. package/dist/client/index.d.ts +3 -3
  16. package/dist/client/index.d.ts.map +1 -1
  17. package/dist/client/index.js +40 -75
  18. package/dist/client/index.js.map +1 -1
  19. package/dist/client/{use-form-field.d.ts → use-field-state.d.ts} +10 -7
  20. package/dist/client/use-field-state.d.ts.map +1 -0
  21. package/dist/config-types.d.ts +15 -18
  22. package/dist/config-types.d.ts.map +1 -1
  23. package/dist/cookies/index.js.map +1 -1
  24. package/dist/index.js +29 -27
  25. package/dist/index.js.map +1 -1
  26. package/dist/plugins/build-manifest.d.ts.map +1 -1
  27. package/dist/plugins/shims.d.ts.map +1 -1
  28. package/dist/search-params/index.js.map +1 -1
  29. package/dist/server/action-client.d.ts +11 -172
  30. package/dist/server/action-client.d.ts.map +1 -1
  31. package/dist/server/action-handler.d.ts +0 -7
  32. package/dist/server/action-handler.d.ts.map +1 -1
  33. package/dist/server/action-schema.d.ts +126 -0
  34. package/dist/server/action-schema.d.ts.map +1 -0
  35. package/dist/server/action-types.d.ts +108 -0
  36. package/dist/server/action-types.d.ts.map +1 -0
  37. package/dist/server/form-data.d.ts +7 -0
  38. package/dist/server/form-data.d.ts.map +1 -1
  39. package/dist/server/index.d.ts +3 -2
  40. package/dist/server/index.d.ts.map +1 -1
  41. package/dist/server/index.js +511 -148
  42. package/dist/server/index.js.map +1 -1
  43. package/dist/server/internal.js +12 -3
  44. package/dist/server/internal.js.map +1 -1
  45. package/dist/server/pipeline-metadata.d.ts +9 -0
  46. package/dist/server/pipeline-metadata.d.ts.map +1 -1
  47. package/dist/server/pipeline-phases.d.ts.map +1 -1
  48. package/dist/server/rsc-entry/action-dispatcher.d.ts +0 -3
  49. package/dist/server/rsc-entry/action-dispatcher.d.ts.map +1 -1
  50. package/dist/server/rsc-entry/index.d.ts.map +1 -1
  51. package/dist/server/schema-introspection.d.ts +68 -0
  52. package/dist/server/schema-introspection.d.ts.map +1 -0
  53. package/dist/server/sensitive-fields.d.ts +40 -26
  54. package/dist/server/sensitive-fields.d.ts.map +1 -1
  55. package/dist/server/sitemap-handler.d.ts.map +1 -1
  56. package/docs/api/31-api-client.mdx +19 -18
  57. package/docs/api/34-api-config.mdx +1 -1
  58. package/docs/learn/08-forms-and-actions.mdx +57 -23
  59. package/package.json +8 -8
  60. package/src/client/browser-entry/index.ts +7 -1
  61. package/src/client/form.tsx +57 -108
  62. package/src/client/index.ts +3 -3
  63. package/src/client/{use-form-field.ts → use-field-state.ts} +20 -8
  64. package/src/config-types.ts +15 -18
  65. package/src/plugins/build-manifest.ts +12 -27
  66. package/src/plugins/shims.ts +0 -1
  67. package/src/server/action-client.ts +82 -307
  68. package/src/server/action-handler.ts +1 -42
  69. package/src/server/action-schema.ts +203 -0
  70. package/src/server/action-types.ts +145 -0
  71. package/src/server/form-data.ts +7 -0
  72. package/src/server/index.ts +5 -3
  73. package/src/server/pipeline-metadata.ts +11 -1
  74. package/src/server/pipeline-phases.ts +9 -2
  75. package/src/server/rsc-entry/action-dispatcher.ts +0 -4
  76. package/src/server/rsc-entry/index.ts +1 -2
  77. package/src/server/schema-introspection.ts +393 -0
  78. package/src/server/sensitive-fields.ts +115 -58
  79. package/src/server/sitemap-handler.ts +14 -21
  80. package/dist/_chunks/actions-CUh3cClk.js.map +0 -1
  81. package/dist/client/use-form-field.d.ts.map +0 -1
@@ -6,6 +6,15 @@
6
6
  *
7
7
  * See design/16-metadata.md §"Metadata Routes"
8
8
  */
9
+ /**
10
+ * Cache-Control the framework sets on metadata route responses it produces:
11
+ * static files, serialized handler results (sitemap, robots, manifest) and
12
+ * the auto-generated sitemap. A Response a handler returns is sent with its
13
+ * own headers only — the framework adds no default to it.
14
+ *
15
+ * See design/16-metadata.md §"Caching" (under "Metadata Routes")
16
+ */
17
+ export declare const METADATA_CACHE_CONTROL = "public, max-age=14400, must-revalidate";
9
18
  /**
10
19
  * Serve a static metadata file by reading it from disk.
11
20
  *
@@ -1 +1 @@
1
- {"version":3,"file":"pipeline-metadata.d.ts","sourceRoot":"","sources":["../../src/server/pipeline-metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAgBH;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,SAAS,EAAE,OAAO,oBAAoB,EAAE,kBAAkB,GACzD,OAAO,CAAC,QAAQ,CAAC,CAanB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,KAAK,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC,GACD,MAAM,CAoBR;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM,CAMnE;AAED,qCAAqC;AACrC,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAO7C"}
1
+ {"version":3,"file":"pipeline-metadata.d.ts","sourceRoot":"","sources":["../../src/server/pipeline-metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,2CAA2C,CAAC;AAc/E;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,SAAS,EAAE,OAAO,oBAAoB,EAAE,kBAAkB,GACzD,OAAO,CAAC,QAAQ,CAAC,CAanB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,KAAK,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC,GACD,MAAM,CAoBR;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM,CAMnE;AAED,qCAAqC;AACrC,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAO7C"}
@@ -1 +1 @@
1
- {"version":3,"file":"pipeline-phases.d.ts","sourceRoot":"","sources":["../../src/server/pipeline-phases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAsBH,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAoC,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC5F,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAMrF,UAAU,aAAa;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,mBAAmB,CAAC;CACpC;AAID;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,aAAa,EACvB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,GAC7B,OAAO,CAAC,YAAY,CAAC,CAavB;AAID;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,aAAa,EAAE,aAAa,GAC3B,OAAO,CAAC,YAAY,CAAC,CAsDvB;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,EAAE,iBAAiB,EAAE,YAAY,EAAE,EAAE,aAAa,GACjD,OAAO,CAAC,YAAY,CAAC,CAYvB;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,eAAe,CAAC,EAAE,OAAO,GACxB,OAAO,CAAC,QAAQ,CAAC,CAuRnB"}
1
+ {"version":3,"file":"pipeline-phases.d.ts","sourceRoot":"","sources":["../../src/server/pipeline-phases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA0BH,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAoC,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC5F,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAMrF,UAAU,aAAa;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,mBAAmB,CAAC;CACpC;AAID;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,aAAa,EACvB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,GAC7B,OAAO,CAAC,YAAY,CAAC,CAavB;AAID;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,aAAa,EAAE,aAAa,GAC3B,OAAO,CAAC,YAAY,CAAC,CAsDvB;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,EAAE,iBAAiB,EAAE,YAAY,EAAE,EAAE,aAAa,GACjD,OAAO,CAAC,YAAY,CAAC,CAYvB;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,eAAe,CAAC,EAAE,OAAO,GACxB,OAAO,CAAC,QAAQ,CAAC,CA0RnB"}
@@ -22,7 +22,6 @@
22
22
  import type { BodyLimitsConfig } from '../body-limits.ts';
23
23
  import type { CsrfConfig } from '../csrf.ts';
24
24
  import type { PipelineReentry, RouteMatcher } from '../pipeline.ts';
25
- import type { SensitiveFieldsOption } from '../sensitive-fields.ts';
26
25
  import type { RevalidateRenderer } from '../actions.ts';
27
26
  /**
28
27
  * Build a `RevalidateRenderer` for a specific request.
@@ -40,8 +39,6 @@ export interface ActionDispatcherDeps {
40
39
  csrfConfig: CsrfConfig;
41
40
  /** Body size limits forwarded to `handleActionRequest`. */
42
41
  bodyLimits?: BodyLimitsConfig['limits'];
43
- /** Sensitive-field deny-list forwarded to `handleActionRequest`. */
44
- sensitiveFields?: SensitiveFieldsOption;
45
42
  /** Per-request factory that builds a `RevalidateRenderer`. */
46
43
  buildRevalidateRenderer: RevalidateRendererFactory;
47
44
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"action-dispatcher.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/action-dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEpE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AACpE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAIxD;;;;;;;;GAQG;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,kBAAkB,CAAC;AAE7E,yEAAyE;AACzE,MAAM,WAAW,oBAAoB;IACnC,6EAA6E;IAC7E,UAAU,EAAE,UAAU,CAAC;IACvB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IACxC,oEAAoE;IACpE,eAAe,CAAC,EAAE,qBAAqB,CAAC;IACxC,8DAA8D;IAC9D,uBAAuB,EAAE,yBAAyB,CAAC;IACnD;;;;;;OAMG;IACH,UAAU,EAAE,YAAY,CAAC;CAC1B;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,oBAAoB,GACzB,CACD,GAAG,EAAE,OAAO,EACZ,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,QAAQ,CAAC,KACnE,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAiE5B"}
1
+ {"version":3,"file":"action-dispatcher.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/action-dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEpE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAIxD;;;;;;;;GAQG;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,kBAAkB,CAAC;AAE7E,yEAAyE;AACzE,MAAM,WAAW,oBAAoB;IACnC,6EAA6E;IAC7E,UAAU,EAAE,UAAU,CAAC;IACvB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IACxC,8DAA8D;IAC9D,uBAAuB,EAAE,yBAAyB,CAAC;IACnD;;;;;;OAMG;IACH,UAAU,EAAE,YAAY,CAAC;CAC1B;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,oBAAoB,GACzB,CACD,GAAG,EAAE,OAAO,EACZ,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,QAAQ,CAAC,KACnE,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAgE5B"}
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/index.ts"],"names":[],"mappings":"AA0CA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AA8ClE;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAEjD;AAiVD,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAInE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAK1D,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAItE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,OAAO,wBAAwB,EAAE,cAAc,GACvD,OAAO,CAAC,OAAO,wBAAwB,EAAE,cAAc,CAAC,CAE1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,OAAO,wBAAwB,EAAE,uBAAuB,GAChE,OAAO,CAAC,OAAO,wBAAwB,EAAE,uBAAuB,CAAC,CAQnE;8BAwCoB,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/index.ts"],"names":[],"mappings":"AA0CA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AA8ClE;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAEjD;AAgVD,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAInE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAK1D,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAItE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,OAAO,wBAAwB,EAAE,cAAc,GACvD,OAAO,CAAC,OAAO,wBAAwB,EAAE,cAAc,CAAC,CAE1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,OAAO,wBAAwB,EAAE,uBAAuB,GAChE,OAAO,CAAC,OAAO,wBAAwB,EAAE,uBAAuB,CAAC,CAQnE;8BAwCoB,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC"}
@@ -0,0 +1,68 @@
1
+ /**
2
+ * Schema introspection — the shape of an action's input as its schema
3
+ * declares it: which fields are lists, which may be absent, and which the
4
+ * schema marks sensitive.
5
+ *
6
+ * Standard Schema v1 has no introspection API, so this feature-detects what
7
+ * the libraries expose:
8
+ *
9
+ * - **Zod 4**: its schema tree (`_zod.def`, documented for library authors),
10
+ * with `.meta()` for marks and `_zod.optin` for fields that may be absent.
11
+ * Not Zod's JSON Schema: that describes a `z.preprocess(fn, z.array(…))`
12
+ * field as the inner array, and wrapping a scalar before `fn` runs would
13
+ * hand a comma-splitting preprocessor `['a,b']`. A preprocessed field is
14
+ * its author's to read, so it has no shape here.
15
+ * - **Valibot**: its schema objects (`entries`, `item`, `wrapped`, `options`),
16
+ * with `v.metadata({ sensitive: true })` read from the pipe.
17
+ * - **Standard JSON Schema** (`~standard.jsonSchema.input()`) for any other
18
+ * library that implements it, such as ArkType, whose
19
+ * `.configure({ sensitive: true })` lands in the JSON Schema node.
20
+ *
21
+ * Any other schema (a legacy `.parse()` schema, Zod 3, a hand-written
22
+ * Standard Schema) has no shape: its form input is not normalized and only
23
+ * the name deny-list strips its echo.
24
+ *
25
+ * A union merges its branches: a field is sensitive if any branch marks it,
26
+ * and a list only if every branch declares it one. An intersection merges
27
+ * its parts, which all apply: a list or sensitive if any part says so.
28
+ *
29
+ * `createActionClient` computes the shape once per action and keeps it on the
30
+ * action's closure. It is used twice, by `normalizeListFields` (before
31
+ * validation, and for `submittedValues`) and by `stripSensitiveFields`.
32
+ *
33
+ * See design/08-forms-and-actions.md §"The Form Model" and
34
+ * §"Sensitive field stripping".
35
+ */
36
+ /** The declared shape of one field (or of the whole input). */
37
+ export interface FieldShape {
38
+ /** The field holds items of this shape (a list, possibly not in every union branch). */
39
+ item?: FieldShape;
40
+ /** Every declaration of the field is a list: normalize its form value to an array. */
41
+ list?: boolean;
42
+ /** The field is an object; these are its properties' shapes. */
43
+ properties?: Record<string, FieldShape>;
44
+ /** The field may be absent (`.optional()`, a default, a missing union branch). */
45
+ optional?: boolean;
46
+ /** The schema marks the field sensitive (`.meta({ sensitive: true })`). */
47
+ sensitive?: boolean;
48
+ }
49
+ /**
50
+ * The shape of `schema`'s input, or `undefined` when the schema library
51
+ * exposes nothing to read it from.
52
+ */
53
+ export declare function introspectSchema(schema: unknown): FieldShape | undefined;
54
+ /**
55
+ * Give every field the schema declares as a list the same shape whatever its
56
+ * count. `parseFormData` reads a repeated name as an array, a single value as
57
+ * a scalar, and an absent name not at all; here a scalar becomes `[value]`,
58
+ * and an absent or blank required list becomes `[]` (blanks are dropped from
59
+ * a list, as `parseFormData` drops them from a repeated name). An optional
60
+ * list that was not submitted (or was one blank) is absent, so `.optional()` still means
61
+ * "not sent". Lists inside lists and objects are normalized too. An object
62
+ * where a list is declared (an indexed list with a gap) is left for the
63
+ * schema to reject.
64
+ *
65
+ * Returns a copy; the input is not written to.
66
+ */
67
+ export declare function normalizeListFields(values: Record<string, unknown>, shape: FieldShape | undefined): Record<string, unknown>;
68
+ //# sourceMappingURL=schema-introspection.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"schema-introspection.d.ts","sourceRoot":"","sources":["../../src/server/schema-introspection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAIH,+DAA+D;AAC/D,MAAM,WAAW,UAAU;IACzB,wFAAwF;IACxF,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,sFAAsF;IACtF,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxC,kFAAkF;IAClF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAiBxE;AAwPD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,KAAK,EAAE,UAAU,GAAG,SAAS,GAC5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAGzB"}
@@ -1,32 +1,42 @@
1
1
  /**
2
- * Sensitive field stripping — removes password/token/CVV-style fields
3
- * from form values before they are echoed back to the client as
4
- * `submittedValues` for form repopulation.
2
+ * Sensitive field stripping — removes password/token/CVV-style fields from
3
+ * the `submittedValues` a `createActionClient` action echoes back to the
4
+ * client for form repopulation.
5
5
  *
6
- * Applied to both action paths:
7
- * - With-JS action path: `createActionClient()` in `action-client.ts`
8
- * - No-JS form POST path: `handleFormAction()` in `action-handler.ts`
6
+ * **This is hygiene, not a security boundary.** `submittedValues` only ever
7
+ * returns to the user who typed it, in the response to their own POST:
9
8
  *
10
- * Why: on a validation failure, timber echoes submitted form values back so
11
- * the user doesn't have to re-type everything. Without filtering, plaintext
12
- * passwords / credit-card numbers / TOTP codes would travel through the RSC
13
- * stream (with-JS) or land in the HTML as `defaultValue` attributes (no-JS)
14
- * — ending up in browser history, proxy logs, disk caches, and the
15
- * back-forward cache.
9
+ * - With JavaScript, it travels in the action's response, a non-cacheable
10
+ * POST fetch. What remains is exposure to devtools, HAR exports and
11
+ * TLS-inspecting proxies.
12
+ * - Without JavaScript, it is rendered into the page's HTML as a field's
13
+ * `defaultValue`: one uncached response, but one that view-source, the
14
+ * back-forward cache and a shared machine can surface. OWASP advises not
15
+ * pre-filling password fields for this reason.
16
16
  *
17
- * Safe by default: the built-in deny-list is applied unconditionally unless
18
- * the user explicitly opts out via `forms.stripSensitiveFields: false` in
19
- * `timber.config.ts` or per-action via `createActionClient({ stripSensitiveFields: false })`.
17
+ * The main reason to strip is UX: a password or card field comes back empty
18
+ * after a failed submit, as users expect.
20
19
  *
21
- * See design/08-forms-and-actions.md §"Validation errors"
20
+ * What is stripped: a field whose name matches the built-in deny-list (or the
21
+ * configured option), and a field the action's schema marks sensitive with
22
+ * `.meta({ sensitive: true })` (Valibot: `v.metadata({ sensitive: true })`),
23
+ * at its exact path. The schema mark covers names the list misses
24
+ * (`recoveryPhrase`) and always applies, even with the name list turned off.
25
+ *
26
+ * Only `createActionClient` strips, because only it builds `submittedValues`.
27
+ * A raw `'use server'` action owns its return value: whatever it returns is
28
+ * what the client gets, on both paths.
29
+ *
30
+ * See design/08-forms-and-actions.md §"Sensitive field stripping"
22
31
  * See design/13-security.md §"Sensitive field stripping"
23
- * See TIM-816
24
32
  */
33
+ import type { FieldShape } from './schema-introspection.ts';
25
34
  /**
26
- * How to strip sensitive fields from `submittedValues`.
35
+ * How to strip sensitive fields from `submittedValues`, by name.
27
36
  *
28
- * - `true` / `undefined` — use the built-in deny-list (default, safe).
29
- * - `false` — do not strip anything (dev convenience; never do this in prod).
37
+ * - `true` / `undefined` — use the built-in deny-list (default).
38
+ * - `false` — strip no field by name. Fields the schema marks sensitive are
39
+ * still stripped.
30
40
  * - `string[]` — additional field names to strip, merged with the built-in list.
31
41
  * - `(name) => boolean` — custom predicate, fully replaces the built-in list.
32
42
  * Return `true` to strip, `false` to keep. The `name` argument is the raw
@@ -34,7 +44,7 @@
34
44
  */
35
45
  export type SensitiveFieldsOption = boolean | readonly string[] | ((name: string) => boolean);
36
46
  /**
37
- * A resolved predicate: `null` means "don't strip anything" (the option was
47
+ * A resolved predicate: `null` means "strip no field by name" (the option was
38
48
  * explicitly `false`). Otherwise a function from raw field name → boolean.
39
49
  */
40
50
  export type ResolvedSensitivePredicate = ((name: string) => boolean) | null;
@@ -44,7 +54,7 @@ export type ResolvedSensitivePredicate = ((name: string) => boolean) | null;
44
54
  *
45
55
  * - Per-action `undefined` → fall back to global.
46
56
  * - Global `undefined` → use built-in list.
47
- * - Either level set to `false` → disable stripping entirely (returns `null`).
57
+ * - Either level set to `false` → no name matching (returns `null`).
48
58
  * - `true` → built-in list.
49
59
  * - `string[]` → built-in ∪ extras.
50
60
  * - function → custom, replaces the built-in list entirely.
@@ -58,9 +68,11 @@ export declare function setGlobalSensitiveFieldsConfig(option: SensitiveFieldsOp
58
68
  /** Read the global `forms.stripSensitiveFields` config. */
59
69
  export declare function getGlobalSensitiveFieldsConfig(): SensitiveFieldsOption | undefined;
60
70
  /**
61
- * Walk an object (recursively) and return a copy with every key matching
62
- * `predicate` removed. Nested objects like `{ user: { password: '...' } }`
63
- * are handled — `user.password` is stripped while other `user.*` fields remain.
71
+ * Walk an object (recursively) and return a copy without its sensitive
72
+ * fields: every key `predicate` matches, and every field `shape` (the
73
+ * schema's declared shape) marks sensitive. Nested objects like
74
+ * `{ user: { password: '...' } }` are handled — `user.password` is stripped
75
+ * while other `user.*` fields remain.
64
76
  *
65
77
  * - Arrays are walked element-wise (object entries inside arrays are cleaned).
66
78
  * - Non-plain values (strings, numbers, Files, Dates, etc.) are returned as-is.
@@ -68,7 +80,9 @@ export declare function getGlobalSensitiveFieldsConfig(): SensitiveFieldsOption
68
80
  * — we do NOT set it to an empty string, because that would overwrite a
69
81
  * valid `defaultValue` the form author might have set.
70
82
  */
71
- export declare function stripSensitiveFields<T>(value: T, predicate: ResolvedSensitivePredicate): T;
83
+ export declare function stripSensitiveFields(value: Record<string, unknown>, predicate: ResolvedSensitivePredicate, shape?: FieldShape): Record<string, unknown>;
84
+ /** The built-in patterns, for the docs drift test. */
85
+ export declare const __BUILTIN_SENSITIVE_PATTERNS: readonly string[];
72
86
  /** Reset the "warned once" cache. Exposed for tests. */
73
87
  export declare function __resetSensitiveFieldsWarnings(): void;
74
88
  //# sourceMappingURL=sensitive-fields.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"sensitive-fields.d.ts","sourceRoot":"","sources":["../../src/server/sensitive-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH;;;;;;;;;GASG;AACH,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,SAAS,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC;AAoF9F;;;GAGG;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,IAAI,CAAC;AAE5E;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,qBAAqB,GAAG,SAAS,EAC5C,MAAM,EAAE,qBAAqB,GAAG,SAAS,GACxC,0BAA0B,CAa5B;AAMD;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,qBAAqB,GAAG,SAAS,GAAG,IAAI,CAE9F;AAED,2DAA2D;AAC3D,wBAAgB,8BAA8B,IAAI,qBAAqB,GAAG,SAAS,CAElF;AAkBD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,SAAS,EAAE,0BAA0B,GAAG,CAAC,CAoB1F;AAID,wDAAwD;AACxD,wBAAgB,8BAA8B,IAAI,IAAI,CAErD"}
1
+ {"version":3,"file":"sensitive-fields.d.ts","sourceRoot":"","sources":["../../src/server/sensitive-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAI5D;;;;;;;;;;GAUG;AACH,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,SAAS,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC;AAkG9F;;;GAGG;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,IAAI,CAAC;AAE5E;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,qBAAqB,GAAG,SAAS,EAC5C,MAAM,EAAE,qBAAqB,GAAG,SAAS,GACxC,0BAA0B,CAa5B;AAMD;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,qBAAqB,GAAG,SAAS,GAAG,IAAI,CAE9F;AAED,2DAA2D;AAC3D,wBAAgB,8BAA8B,IAAI,qBAAqB,GAAG,SAAS,CAElF;AAoBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,SAAS,EAAE,0BAA0B,EACrC,KAAK,CAAC,EAAE,UAAU,GACjB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAGzB;AAuCD,sDAAsD;AACtD,eAAO,MAAM,4BAA4B,EAAE,SAAS,MAAM,EAIzD,CAAC;AAEF,wDAAwD;AACxD,wBAAgB,8BAA8B,IAAI,IAAI,CAErD"}
@@ -1 +1 @@
1
- {"version":3,"file":"sitemap-handler.d.ts","sourceRoot":"","sources":["../../src/server/sitemap-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AASH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAKvD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,WAAW,EACjB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACrC,CAAC,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC,GAAG,SAAS,CAyH9D"}
1
+ {"version":3,"file":"sitemap-handler.d.ts","sourceRoot":"","sources":["../../src/server/sitemap-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAUH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAevD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,WAAW,EACjB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACrC,CAAC,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC,GAAG,SAAS,CAuG9D"}
@@ -123,51 +123,52 @@ const params = useSegmentParams(); // Partial<AllSegmentParams>
123
123
 
124
124
  ## Form Hooks
125
125
 
126
- Forms use React's own `useActionState`, imported from `react`. An action built with `createActionClient` passes to it directly: `result` is typed from the action, and the dispatch accepts the submitted `FormData` or the schema's input.
126
+ Forms use React's own `useActionState`, imported from `react`. An action built with `createActionClient` passes to it directly: `result` is typed from the action, and the dispatch accepts the submitted `FormData` or the schema's input. For a call that isn't a form submit, such as a delete button, dispatch inside a transition: `startTransition(() => dispatch({ id }))`.
127
127
 
128
- ### `parseFormErrors(result)`
128
+ ### `readFormErrors(result)`
129
129
 
130
130
  Reads the errors out of an action result. `_root` validation errors are form-level; every other key is a field.
131
131
 
132
132
  ```tsx
133
133
  import { useActionState } from 'react';
134
- import { parseFormErrors } from '@timber-js/app/client';
134
+ import { readFormErrors } from '@timber-js/app/client';
135
135
 
136
136
  const [result, action, isPending] = useActionState(createTodo, null);
137
- const errors = parseFormErrors(result);
137
+ const errors = readFormErrors(result);
138
138
 
139
+ errors.field('title'); // string | null: the first error for the field
140
+ errors.form; // string[]: form-level errors
141
+ errors.server; // { code, data? } | null
139
142
  errors.hasErrors; // boolean
140
- errors.fieldErrors; // Record<string, string[]>
141
- errors.formErrors; // string[]
142
- errors.serverError; // { code, data? } | null
143
- errors.getFieldError('title'); // string | null
144
143
  ```
145
144
 
146
- ### `useFormField(defaultValue)`
145
+ `errors.field()` is typed from the action's schema: it takes the dot paths of the schema's input, such as `'title'` or `'sets.0.name'`, so a misspelled field name is a type error. An action without a schema accepts any name.
146
+
147
+ ### `useFieldState(defaultValue)`
147
148
 
148
149
  State for a form field that needs JavaScript, such as a combobox or a chip list, that follows the form's reset like a native input with a `defaultValue`. React resets a form after every action, so use this instead of `useState` for any field inside a form. See [Keeping What the User Typed](/docs/forms-and-actions#keeping-what-the-user-typed).
149
150
 
150
151
  ```tsx
151
- import { useFormField } from '@timber-js/app/client';
152
+ import { useFieldState } from '@timber-js/app/client';
152
153
 
153
154
  // draft = toDraft(result?.submittedValues ?? post): the form's defaults
154
- const [tags, setTags, ref] = useFormField(draft.tags);
155
+ const [tags, setTags, ref] = useFieldState(draft.tags);
155
156
 
156
157
  <div ref={ref}>
157
- <input type="hidden" name="tags" value={tags.join(',')} />
158
+ {tags.map((tag) => (
159
+ <input key={tag} type="hidden" name="tags" value={tag} />
160
+ ))}
158
161
  <TagPicker value={tags} onChange={setTags} />
159
- </div>
162
+ </div>;
160
163
  ```
161
164
 
162
165
  - `value`: `defaultValue` until `setValue` is called, then the edit. An unedited field follows a new `defaultValue`.
163
166
  - `setValue`: like a `useState` setter; accepts a value or an updater.
164
- - `ref`: attach to any element inside the `<form>`. When the form resets, the edit is dropped and `value` is `defaultValue` again, unless the form cancels the `reset` event.
165
-
166
- An edit dispatches a bubbling `change` event from the `ref` element, so a native `change` listener on the form sees it. React's `onChange` prop does not: it only reports inputs, selects and textareas. Render the value into the form data yourself, usually with a hidden input.
167
+ - `ref`: attach to any element inside the `<form>`, or to the `<form>` itself. When the form resets, the edit is dropped and `value` is `defaultValue` again, unless the form cancels the `reset` event.
167
168
 
168
- ### `useFormAction(action)`
169
+ An edit dispatches a bubbling `change` event from the `ref` element, so a native `change` listener on the form sees it. React's `onChange` prop does not: it only reports inputs, selects and textareas. Render the value into the form data yourself, usually with hidden inputs. A list can be one hidden input per item: a `createActionClient` action reads none, one or many values as a list when its schema declares one.
169
170
 
170
- Bind a server action to a form with pending state.
171
+ With the `ref` on the `<form>`, the hook can sit above the form and hold the whole draft as one object, for a preview outside the form. See [Where form state lives](/docs/forms-and-actions#where-form-state-lives).
171
172
 
172
173
  ## Utilities
173
174
 
@@ -153,7 +153,7 @@ limits: {
153
153
  - **Type:** `boolean | string[]`
154
154
  - **Default:** `true`
155
155
 
156
- Strip sensitive fields (passwords, tokens, CVV, SSN, etc.) from the `submittedValues` echoed back when an action fails. `true` uses the built-in deny-list; an array adds extra field names to the built-in list; `false` disables stripping (never do this in production). See [Forms & Server Actions](/docs/forms-and-actions) for the full pattern list.
156
+ Strip sensitive fields (passwords, tokens, CVV, SSN, etc.) from the `submittedValues` a `createActionClient` action echoes back when it fails. `true` uses the built-in deny-list; an array adds extra field names to the built-in list; `false` turns off matching by name (fields the schema marks `.meta({ sensitive: true })` are still stripped). A client's own `stripSensitiveFields` option overrides this. See [Advanced Forms](/docs/advanced-forms#sensitive-field-stripping) for the full pattern list.
157
157
 
158
158
  ### `pageExtensions`
159
159
 
@@ -52,22 +52,22 @@ The `.schema()` method accepts any Standard Schema-compatible validator — Zod,
52
52
  'use client';
53
53
 
54
54
  import { useActionState } from 'react';
55
- import { parseFormErrors } from '@timber-js/app/client';
55
+ import { readFormErrors } from '@timber-js/app/client';
56
56
  import { createTodo } from './actions';
57
57
 
58
58
  export default function TodoForm() {
59
59
  const [state, action, pending] = useActionState(createTodo, null);
60
- const errors = parseFormErrors(state);
60
+ const errors = readFormErrors(state);
61
61
 
62
62
  return (
63
63
  <form action={action}>
64
64
  <div>
65
65
  <input name="title" required />
66
- {errors.getFieldError('title') && (
67
- <p className="text-red-600">{errors.getFieldError('title')}</p>
66
+ {errors.field('title') && (
67
+ <p className="text-red-600">{errors.field('title')}</p>
68
68
  )}
69
69
  </div>
70
- {errors.serverError && (
70
+ {errors.server && (
71
71
  <p className="text-red-600">Something went wrong. Please try again.</p>
72
72
  )}
73
73
  <button type="submit" disabled={pending}>
@@ -82,19 +82,22 @@ export default function TodoForm() {
82
82
 
83
83
  ### Form Errors
84
84
 
85
- `parseFormErrors` from `@timber-js/app/client` reads the errors out of the result:
85
+ `readFormErrors` from `@timber-js/app/client` reads the errors out of the result:
86
86
 
87
87
  ```tsx
88
88
  const [state, action, pending] = useActionState(myAction, null);
89
- const errors = parseFormErrors(state);
89
+ const errors = readFormErrors(state);
90
90
 
91
- errors.fieldErrors; // Record<string, string[]>
92
- errors.formErrors; // string[] (form-level errors)
93
- errors.serverError; // { code: string; data?: Record<string, unknown> } | null
94
- errors.hasErrors; // boolean
95
- errors.getFieldError('title'); // string | null (first error for field)
91
+ errors.field('title'); // string | null (first error for the field)
92
+ errors.form; // string[] (form-level errors)
93
+ errors.server; // { code: string; data?: Record<string, unknown> } | null
94
+ errors.hasErrors; // boolean
96
95
  ```
97
96
 
97
+ `errors.field()` takes the field names of the action's schema, including paths into lists like `'sets.0.name'`, so a typo is a type error.
98
+
99
+ An action can also run outside a form, from a delete button for example. Dispatch it inside a transition: `startTransition(() => dispatch({ id }))`. A direct call takes the schema's input types, before coercion, so `deleteTodo({ id: 5 })` works with `id: z.coerce.number()`.
100
+
98
101
  ## Keeping What the User Typed
99
102
 
100
103
  React resets a form after every action: each field goes back to its `defaultValue`. Build forms on that reset, and they keep the user's input after a failure and show the saved values after a save, with or without JavaScript:
@@ -120,7 +123,8 @@ export const saveEvent = action
120
123
  category: z.string(),
121
124
  ticketed: z.preprocess(coerce.checkbox, z.boolean()),
122
125
  // sets.0.name, sets.1.name… arrive as an array
123
- sets: z.array(z.object({ name: z.string().min(1) })).default([]), // no rows: no key
126
+ // no rows at all arrive as []
127
+ sets: z.array(z.object({ name: z.string().min(1) })),
124
128
  })
125
129
  )
126
130
  .action(async ({ input }) => {
@@ -129,7 +133,7 @@ export const saveEvent = action
129
133
  });
130
134
  ```
131
135
 
132
- `submittedValues` is the raw form: strings, lists as arrays, an unchecked box absent. Page data is typed. One small, lenient function reads either into what the fields render:
136
+ `submittedValues` is the raw form: strings, an unchecked box absent, and every field the schema declares as a list as an array, whether it was submitted zero, one or many times. Page data is typed. One small, lenient function reads either into what the fields render:
133
137
 
134
138
  ```ts title="app/events/[id]/draft.ts"
135
139
  export function toDraft(values: Record<string, unknown>) {
@@ -148,7 +152,7 @@ export function toDraft(values: Record<string, unknown>) {
148
152
  'use client';
149
153
 
150
154
  import { useActionState } from 'react';
151
- import { parseFormErrors } from '@timber-js/app/client';
155
+ import { readFormErrors } from '@timber-js/app/client';
152
156
  import { saveEvent } from './actions';
153
157
  import { toDraft } from './draft';
154
158
 
@@ -156,7 +160,7 @@ type Event = { id: string; title: string; category: string; ticketed: boolean; s
156
160
 
157
161
  export function EventForm({ event }: { event: Event }) {
158
162
  const [result, action, pending] = useActionState(saveEvent, null);
159
- const errors = parseFormErrors(result);
163
+ const errors = readFormErrors(result);
160
164
  // After a failure: what the user submitted. Otherwise: the saved event.
161
165
  const d = toDraft(result?.submittedValues ?? event);
162
166
 
@@ -164,7 +168,7 @@ export function EventForm({ event }: { event: Event }) {
164
168
  <form action={action}>
165
169
  <input type="hidden" name="id" value={event.id} />
166
170
  <input name="title" defaultValue={d.title} />
167
- {errors.getFieldError('title')}
171
+ {errors.field('title')}
168
172
 
169
173
  {/* React applies a select's defaultValue only on mount: key it on the default */}
170
174
  <select key={d.category} name="category" defaultValue={d.category}>
@@ -178,7 +182,7 @@ export function EventForm({ event }: { event: Event }) {
178
182
  <input key={i} name={`sets.${i}.name`} defaultValue={set.name} />
179
183
  ))}
180
184
 
181
- {errors.serverError && <p>Could not save. Please try again.</p>}
185
+ {errors.server && <p>Could not save. Please try again.</p>}
182
186
  <button disabled={pending}>Save</button>
183
187
  </form>
184
188
  );
@@ -191,22 +195,52 @@ Three things break the model:
191
195
 
192
196
  - **Controlled fields.** A field whose value lives in state keeps showing that state after the reset has put the DOM back to its default, and the next submit sends what the DOM holds, not what the user sees. If a form must be controlled, cancel the reset: `<form action={action} onReset={(e) => e.preventDefault()}>`.
193
197
  - **An unkeyed `<select>`.** React ignores a changed `defaultValue` on a mounted `<select>`. Key it on its default, as above. Inputs, checkboxes and textareas don't need this.
194
- - **`useState` for a field that needs JavaScript.** A combobox or a chip list can't be a native input. Hold its state in `useFormField` instead, which follows the reset like a native input:
198
+ - **`useState` for a field that needs JavaScript.** A combobox or a chip list can't be a native input. Hold its state in `useFieldState` instead, which follows the reset like a native input:
195
199
 
196
200
  ```tsx
197
- import { useFormField } from '@timber-js/app/client';
201
+ import { useFieldState } from '@timber-js/app/client';
198
202
 
199
203
  function TagsField({ defaultValue }: { defaultValue: string[] }) {
200
- const [tags, setTags, ref] = useFormField(defaultValue);
204
+ const [tags, setTags, ref] = useFieldState(defaultValue);
201
205
  return (
202
206
  <div ref={ref}>
203
- <input type="hidden" name="tags" value={tags.join(',')} />
207
+ {tags.map((tag) => (
208
+ <input key={tag} type="hidden" name="tags" value={tag} />
209
+ ))}
204
210
  <TagPicker value={tags} onChange={setTags} />
205
211
  </div>
206
212
  );
207
213
  }
208
214
  ```
209
215
 
216
+ ## Where Form State Lives
217
+
218
+ Pick where a form's state lives by what needs to read it.
219
+
220
+ **In the form (the default).** Everything above: uncontrolled fields with defaults from `result?.submittedValues ?? pageData`, and `useFieldState` for fields that need JavaScript. It works without JavaScript. Start here.
221
+
222
+ **Above the form, still resetting.** When something outside the form needs the draft, such as a live preview, call `useFieldState` above the form with the whole draft and put its `ref` on the `<form>` itself. The draft follows the reset like a native field, so it lands on the user's input after a failure and on the saved values after a save, and the form still works without JavaScript:
223
+
224
+ ```tsx
225
+ const defaults = toDraft(result?.submittedValues ?? note);
226
+ const [draft, setDraft, ref] = useFieldState(defaults);
227
+
228
+ return (
229
+ <>
230
+ <Preview title={draft.title} />
231
+ <form ref={ref} action={action}>
232
+ <input
233
+ name="title"
234
+ value={draft.title}
235
+ onChange={(e) => setDraft({ ...draft, title: e.target.value })}
236
+ />
237
+ </form>
238
+ </>
239
+ );
240
+ ```
241
+
242
+ **In your app.** A multi-step wizard, fields that appear depending on other answers, or a draft shared across pages can't be one mounted set of fields: an earlier step's inputs are gone by the time the form submits, so `submittedValues` only has the current step. Keep the values in app state, render the other steps as hidden inputs, and cancel React's reset with `onReset={(e) => e.preventDefault()}`. This needs JavaScript, so use it only when the form can't be one set of fields.
243
+
210
244
  ## After Mutation
211
245
 
212
246
  | Pattern | When to use |
@@ -219,7 +253,7 @@ function TagsField({ defaultValue }: { defaultValue: string[] }) {
219
253
 
220
254
  The same form works with JavaScript disabled, with no extra code. When a no-JS submission's action returns instead of redirecting, timber renders the page again and React hands the result to the `useActionState` hook that submitted it. `result` holds the result on both paths, so errors and the fields' defaults render the same way, and the server writes the user's input back into the HTML.
221
255
 
222
- The result goes only to the hook that submitted, so two forms on one page never see each other's results. It has the same types on both paths: a `Date` your action returns is a `Date` in `state` whether or not JavaScript ran. Sensitive fields (password, apiKey, cvv, etc.) are automatically stripped from `submittedValues`.
256
+ The result goes only to the hook that submitted, so two forms on one page never see each other's results. It has the same types on both paths: a `Date` your action returns is a `Date` in `state` whether or not JavaScript ran. Sensitive fields (password, apiKey, cvv, etc.) are left out of the `submittedValues` a `createActionClient` action returns, and so are fields the schema marks with `.meta({ sensitive: true })`, so a password field comes back empty after a failed submit.
223
257
 
224
258
  A form that doesn't use `useActionState` gets no result back, just as with JavaScript, where React discards a plain `<form action>`'s return value. Such an action should `redirect()` to a page that shows the new state (post-redirect-get). An action that throws renders the nearest `error.tsx`: with JavaScript the action rejects to the nearest error boundary, and without it the page answers from the same `error.tsx` with a 500; return errors from `createActionClient` actions instead.
225
259
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@timber-js/app",
3
- "version": "0.2.0-alpha.217",
3
+ "version": "0.2.0-alpha.219",
4
4
  "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
5
5
  "keywords": [
6
6
  "cloudflare-workers",
@@ -152,13 +152,13 @@
152
152
  },
153
153
  "dependencies": {
154
154
  "@opentelemetry/api": "^1.9.1",
155
- "@opentelemetry/context-async-hooks": "^2.11.0",
156
- "@opentelemetry/sdk-trace-base": "^2.11.0",
155
+ "@opentelemetry/context-async-hooks": "^2.12.0",
156
+ "@opentelemetry/sdk-trace-base": "^2.12.0",
157
157
  "cookie": "^2.0.1",
158
158
  "jsonc-parser": "^3.3.1",
159
- "magic-string": "^1.4.1",
159
+ "magic-string": "^1.4.3",
160
160
  "nitro": "3.0.260903-beta",
161
- "oxc-transform-react": "^0.150.0",
161
+ "oxc-transform-react": "^0.153.0",
162
162
  "srvx": "^1.0.5"
163
163
  },
164
164
  "peerDependencies": {
@@ -167,10 +167,10 @@
167
167
  "@content-collections/vite": "^0.2.0 || ^0.3.0",
168
168
  "@typescript/native-preview": "^7.0.0-dev.0",
169
169
  "@vitejs/plugin-react": "^6.1.0",
170
- "@vitejs/plugin-rsc": ">=0.5.35",
170
+ "@vitejs/plugin-rsc": "^0.5.35",
171
171
  "nuqs": "^2.0.0",
172
- "react": "^19.3.0",
173
- "react-dom": "^19.3.0",
172
+ "react": "19.3.0",
173
+ "react-dom": "19.3.0",
174
174
  "satteri": "^0.9.5",
175
175
  "vite": "8.3.0",
176
176
  "vite-plugin-satteri": "^0.2.15",
@@ -78,7 +78,13 @@ function bootstrap(runtimeConfig: typeof config, formState: ReactFormState | nul
78
78
 
79
79
  // Static mode: fetch _rsc/*.rsc files instead of route URLs with
80
80
  // Accept headers. Static hosts ignore Accept headers (TIM-1243).
81
- if ((runtimeConfig as Record<string, unknown>).output === 'static') {
81
+ // Only for built output — the .rsc files exist only after static
82
+ // generation, and `timber dev` renders route URLs on request like
83
+ // server mode, so dev keeps the Accept-header fetch path.
84
+ if (
85
+ (runtimeConfig as Record<string, unknown>).output === 'static' &&
86
+ !(runtimeConfig as Record<string, unknown>).dev
87
+ ) {
82
88
  setStaticMode(true);
83
89
  }
84
90