@niscorp/nova 0.1.0

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 (170) hide show
  1. package/ACTION_DOCS.md +552 -0
  2. package/ADAPTER.md +170 -0
  3. package/DESIGN.md +719 -0
  4. package/I18N_DOCS.md +224 -0
  5. package/LAYOUT_DOCS.md +505 -0
  6. package/LICENSE +202 -0
  7. package/REACT_DOCS.md +562 -0
  8. package/README.md +379 -0
  9. package/SHELL_DOCS.md +615 -0
  10. package/TERMINAL_DOCS.md +124 -0
  11. package/dist/adapters/dom/components/index.cjs +473 -0
  12. package/dist/adapters/dom/components/index.cjs.map +1 -0
  13. package/dist/adapters/dom/components/index.d.cts +48 -0
  14. package/dist/adapters/dom/components/index.d.ts +48 -0
  15. package/dist/adapters/dom/components/index.js +420 -0
  16. package/dist/adapters/dom/components/index.js.map +1 -0
  17. package/dist/adapters/dom/index.cjs +171 -0
  18. package/dist/adapters/dom/index.cjs.map +1 -0
  19. package/dist/adapters/dom/index.d.cts +29 -0
  20. package/dist/adapters/dom/index.d.ts +29 -0
  21. package/dist/adapters/dom/index.js +15 -0
  22. package/dist/adapters/dom/index.js.map +1 -0
  23. package/dist/adapters/dom/server.cjs +129 -0
  24. package/dist/adapters/dom/server.cjs.map +1 -0
  25. package/dist/adapters/dom/server.d.cts +15 -0
  26. package/dist/adapters/dom/server.d.ts +15 -0
  27. package/dist/adapters/dom/server.js +37 -0
  28. package/dist/adapters/dom/server.js.map +1 -0
  29. package/dist/adapters/ink/index.d.ts +75 -0
  30. package/dist/adapters/ink/index.js +472 -0
  31. package/dist/adapters/ink/index.js.map +1 -0
  32. package/dist/adapters/react/components/index.cjs +552 -0
  33. package/dist/adapters/react/components/index.cjs.map +1 -0
  34. package/dist/adapters/react/components/index.d.cts +30 -0
  35. package/dist/adapters/react/components/index.d.ts +30 -0
  36. package/dist/adapters/react/components/index.js +12 -0
  37. package/dist/adapters/react/components/index.js.map +1 -0
  38. package/dist/adapters/react/index.cjs +1526 -0
  39. package/dist/adapters/react/index.cjs.map +1 -0
  40. package/dist/adapters/react/index.d.cts +149 -0
  41. package/dist/adapters/react/index.d.ts +149 -0
  42. package/dist/adapters/react/index.js +12 -0
  43. package/dist/adapters/react/index.js.map +1 -0
  44. package/dist/adapters/tty/components/index.cjs +255 -0
  45. package/dist/adapters/tty/components/index.cjs.map +1 -0
  46. package/dist/adapters/tty/components/index.d.cts +40 -0
  47. package/dist/adapters/tty/components/index.d.ts +40 -0
  48. package/dist/adapters/tty/components/index.js +187 -0
  49. package/dist/adapters/tty/components/index.js.map +1 -0
  50. package/dist/adapters/tty/index.cjs +76 -0
  51. package/dist/adapters/tty/index.cjs.map +1 -0
  52. package/dist/adapters/tty/index.d.cts +47 -0
  53. package/dist/adapters/tty/index.d.ts +47 -0
  54. package/dist/adapters/tty/index.js +76 -0
  55. package/dist/adapters/tty/index.js.map +1 -0
  56. package/dist/adapters/vue/components/index.cjs +619 -0
  57. package/dist/adapters/vue/components/index.cjs.map +1 -0
  58. package/dist/adapters/vue/components/index.d.cts +224 -0
  59. package/dist/adapters/vue/components/index.d.ts +224 -0
  60. package/dist/adapters/vue/components/index.js +12 -0
  61. package/dist/adapters/vue/components/index.js.map +1 -0
  62. package/dist/adapters/vue/index.cjs +747 -0
  63. package/dist/adapters/vue/index.cjs.map +1 -0
  64. package/dist/adapters/vue/index.d.cts +98 -0
  65. package/dist/adapters/vue/index.d.ts +98 -0
  66. package/dist/adapters/vue/index.js +127 -0
  67. package/dist/adapters/vue/index.js.map +1 -0
  68. package/dist/agent/index.cjs +178 -0
  69. package/dist/agent/index.cjs.map +1 -0
  70. package/dist/agent/index.d.cts +28 -0
  71. package/dist/agent/index.d.ts +28 -0
  72. package/dist/agent/index.js +30 -0
  73. package/dist/agent/index.js.map +1 -0
  74. package/dist/chunk-2MNLEL45.js +47 -0
  75. package/dist/chunk-2MNLEL45.js.map +1 -0
  76. package/dist/chunk-3HGE3VWK.js +753 -0
  77. package/dist/chunk-3HGE3VWK.js.map +1 -0
  78. package/dist/chunk-4ZID7UX5.js +549 -0
  79. package/dist/chunk-4ZID7UX5.js.map +1 -0
  80. package/dist/chunk-7B3RDENH.js +1982 -0
  81. package/dist/chunk-7B3RDENH.js.map +1 -0
  82. package/dist/chunk-7S5BNPUS.js +54 -0
  83. package/dist/chunk-7S5BNPUS.js.map +1 -0
  84. package/dist/chunk-7TS3YVQR.js +114 -0
  85. package/dist/chunk-7TS3YVQR.js.map +1 -0
  86. package/dist/chunk-EG2RUXJN.js +266 -0
  87. package/dist/chunk-EG2RUXJN.js.map +1 -0
  88. package/dist/chunk-GVBBL36G.js +429 -0
  89. package/dist/chunk-GVBBL36G.js.map +1 -0
  90. package/dist/chunk-I5D2R5UA.js +753 -0
  91. package/dist/chunk-I5D2R5UA.js.map +1 -0
  92. package/dist/chunk-IGLCWXQ3.js +304 -0
  93. package/dist/chunk-IGLCWXQ3.js.map +1 -0
  94. package/dist/chunk-JI7ZRESP.js +64 -0
  95. package/dist/chunk-JI7ZRESP.js.map +1 -0
  96. package/dist/chunk-L5223LLX.js +31 -0
  97. package/dist/chunk-L5223LLX.js.map +1 -0
  98. package/dist/chunk-LA3BSEMX.js +1905 -0
  99. package/dist/chunk-LA3BSEMX.js.map +1 -0
  100. package/dist/chunk-OAMC6R6E.js +121 -0
  101. package/dist/chunk-OAMC6R6E.js.map +1 -0
  102. package/dist/chunk-OGD5CCMZ.js +62 -0
  103. package/dist/chunk-OGD5CCMZ.js.map +1 -0
  104. package/dist/chunk-PF4OJTYU.js +199 -0
  105. package/dist/chunk-PF4OJTYU.js.map +1 -0
  106. package/dist/chunk-PZ5AY32C.js +9 -0
  107. package/dist/chunk-PZ5AY32C.js.map +1 -0
  108. package/dist/chunk-RBU5PHN4.js +8 -0
  109. package/dist/chunk-RBU5PHN4.js.map +1 -0
  110. package/dist/chunk-RQB4PRPV.js +285 -0
  111. package/dist/chunk-RQB4PRPV.js.map +1 -0
  112. package/dist/chunk-V32EVEVM.js +464 -0
  113. package/dist/chunk-V32EVEVM.js.map +1 -0
  114. package/dist/chunk-ZITHBBF3.js +85 -0
  115. package/dist/chunk-ZITHBBF3.js.map +1 -0
  116. package/dist/devtools/index.cjs +1088 -0
  117. package/dist/devtools/index.cjs.map +1 -0
  118. package/dist/devtools/index.d.cts +33 -0
  119. package/dist/devtools/index.d.ts +33 -0
  120. package/dist/devtools/index.js +399 -0
  121. package/dist/devtools/index.js.map +1 -0
  122. package/dist/effects-CndX9K7D.d.cts +123 -0
  123. package/dist/effects-CndX9K7D.d.ts +123 -0
  124. package/dist/endpoints-CD-6Jl-H.d.ts +36 -0
  125. package/dist/endpoints-Dem-EdRx.d.cts +36 -0
  126. package/dist/i18n/index.cjs +299 -0
  127. package/dist/i18n/index.cjs.map +1 -0
  128. package/dist/i18n/index.d.cts +28 -0
  129. package/dist/i18n/index.d.ts +28 -0
  130. package/dist/i18n/index.js +180 -0
  131. package/dist/i18n/index.js.map +1 -0
  132. package/dist/index-CNfzSBe2.d.ts +93 -0
  133. package/dist/index-caZoXSwr.d.cts +93 -0
  134. package/dist/index.cjs +3723 -0
  135. package/dist/index.cjs.map +1 -0
  136. package/dist/index.d.cts +144 -0
  137. package/dist/index.d.ts +144 -0
  138. package/dist/index.js +15 -0
  139. package/dist/index.js.map +1 -0
  140. package/dist/migrations/index.cjs +635 -0
  141. package/dist/migrations/index.cjs.map +1 -0
  142. package/dist/migrations/index.d.cts +97 -0
  143. package/dist/migrations/index.d.ts +97 -0
  144. package/dist/migrations/index.js +50 -0
  145. package/dist/migrations/index.js.map +1 -0
  146. package/dist/palette-CP0wd3bE.d.ts +15 -0
  147. package/dist/palette-lm0bU9i5.d.cts +15 -0
  148. package/dist/primitive-props-BH_EJWIe.d.cts +100 -0
  149. package/dist/primitive-props-BH_EJWIe.d.ts +100 -0
  150. package/dist/primitive-props-CGoJvmcH.d.cts +100 -0
  151. package/dist/primitive-props-CGoJvmcH.d.ts +100 -0
  152. package/dist/reflect/index.cjs +998 -0
  153. package/dist/reflect/index.cjs.map +1 -0
  154. package/dist/reflect/index.d.cts +125 -0
  155. package/dist/reflect/index.d.ts +125 -0
  156. package/dist/reflect/index.js +13 -0
  157. package/dist/reflect/index.js.map +1 -0
  158. package/dist/schemas-DPdeFlCT.d.cts +38 -0
  159. package/dist/schemas-DPdeFlCT.d.ts +38 -0
  160. package/dist/schemas-pMyyuXV7.d.cts +47 -0
  161. package/dist/schemas-pMyyuXV7.d.ts +47 -0
  162. package/dist/types-Boh9ckdG.d.ts +194 -0
  163. package/dist/types-Brc7v_pS.d.ts +198 -0
  164. package/dist/types-ByNSwtUV.d.cts +20 -0
  165. package/dist/types-DdltMfw7.d.ts +20 -0
  166. package/dist/types-De0KpxfI.d.cts +198 -0
  167. package/dist/types-DhHL0twe.d.ts +20 -0
  168. package/dist/types-Dv6JLmgo.d.cts +194 -0
  169. package/dist/types-Q80YtOQt.d.cts +20 -0
  170. package/package.json +237 -0
package/I18N_DOCS.md ADDED
@@ -0,0 +1,224 @@
1
+ # i18n Guide
2
+
3
+ How nova renders an application in more than one language.
4
+
5
+ Nova is **language-blind**, the same way it is surface-blind: it holds no
6
+ dictionary and knows no languages. A host supplies both, exactly as it supplies
7
+ the transform evaluator. What nova provides is the swap, the rules about what
8
+ may be swapped, and the extraction that makes filling a dictionary mechanical.
9
+
10
+ ---
11
+
12
+ ## Turning it on
13
+
14
+ ```ts
15
+ import { createShell } from '@niscorp/nova';
16
+
17
+ const shell = createShell({
18
+ canvases,
19
+ actions,
20
+ phrases: { 'Add a member': 'Mitglied hinzufügen' },
21
+ });
22
+ ```
23
+
24
+ That is the whole wiring. The same two fields exist on any `RenderContext`, on
25
+ `render()` / `renderLayout()`, and on `<Nova.Layout>`:
26
+
27
+ ```tsx
28
+ <Nova.Layout layout={layout} data={data} phrases={book} />
29
+ ```
30
+
31
+ No server involved, no adapter code, and nothing to install.
32
+
33
+ ## Where the swap happens, and why it matters
34
+
35
+ **In the renderer**, at the two points where a `RenderNode` is minted: the line
36
+ that resolves a component's props, and the branch that turns a layout's text
37
+ child into a text node.
38
+
39
+ Every tree in the system comes out of `renderLayout` / `renderLayoutFromStore`,
40
+ and there are three callers — the action runtime, the shell, and
41
+ `<Nova.Layout>`. So an **adapter contains no i18n code at all**. React, dom, tty,
42
+ ink and any adapter written later receive words that are already in the reader's
43
+ language and never learn that a second one exists.
44
+
45
+ That is deliberate. An adapter renders a `RenderNode`; if i18n changed the
46
+ adapter contract, every future adapter would inherit a copy of the same rule and
47
+ they would drift.
48
+
49
+ It also costs less than a pass over the finished tree would: the swap happens on
50
+ a value the renderer is already holding, so it is one dictionary lookup rather
51
+ than a second traversal of everything just built.
52
+
53
+ ## The dictionary is keyed on the source string
54
+
55
+ ```ts
56
+ const book = { 'Add a member': 'Mitglied hinzufügen' };
57
+ ```
58
+
59
+ Not `t('people.add')`. The trade is deliberate, and it cuts both ways:
60
+
61
+ - **For.** Layouts stay readable — a file still says what it draws. Nothing has
62
+ to be threaded through a component, and adding a language touches no layout.
63
+ - **Against.** One English word cannot carry two senses. "Book" the verb and
64
+ "Book" the noun are one key here and two words in German.
65
+
66
+ The answer to the second is not to abandon the approach — it is to disambiguate
67
+ that one string at its author site when it actually bites.
68
+
69
+ ## Proseness is decided by the KEY, never by the value
70
+
71
+ A render tree is mostly not prose. It carries person names, ids, css values,
72
+ tone words, icon names and row data. A pass that translated every string it
73
+ found would rename a member called "Pass" the day the studio started selling
74
+ one.
75
+
76
+ So the host names the carriers and everything else is left alone:
77
+
78
+ ```ts
79
+ phraseKeys: {
80
+ props: [...DEFAULT_PHRASE_KEYS.props, 'sentence'],
81
+ suffixes: ['_display'],
82
+ }
83
+ ```
84
+
85
+ - **`props`** — prop names whose string values are prose. Matched at **any
86
+ depth** inside a prop value, which is what makes a spec prop work: a table's
87
+ `columns: [{ label }]` and a select's `options: [{ label }]` are the same rule
88
+ as a bare `label`. Note this **replaces** the default set, so spread
89
+ `DEFAULT_PHRASE_KEYS.props` when you mean to extend it.
90
+ - **`suffixes`** — suffixes marking a DATA field as a display string. An app
91
+ that spells its read-time display fields `status_display` declares
92
+ `['_display']` once, and every closed-set word a query manufactures becomes
93
+ translatable without naming forty fields. **Closed sets only** — a `_display`
94
+ field holding a formatted date or an amount will simply miss.
95
+ - **`text`** — translate bare text nodes. Default `true`.
96
+
97
+ `DEFAULT_PHRASE_KEYS` covers `label`, `title`, `subtitle`, `heading`, `eyebrow`,
98
+ `lead`, `blurb`, `placeholder`, `hint`, `help`, `message`, `empty`,
99
+ `emptyHint`, `emptyLabel`, `noMatch`, `caption`, `description`, `confirmLabel`,
100
+ `cancelLabel`, `alt`, `tooltip`. Deliberately absent: `name`, `value`, `id`,
101
+ `icon`, `tone`, `variant`, `key` — those carry data or design tokens.
102
+
103
+ ### An authored text child is prose; a bound one is data
104
+
105
+ ```jsonc
106
+ { "children": "Front desk" } // translated — a person wrote it
107
+ { "children": "$.member.surname" } // never — it resolves to data
108
+ ```
109
+
110
+ A text position has no key to protect it, so the renderer uses what only the
111
+ renderer knows: whether the string was authored or resolved. This distinction is
112
+ unrecoverable once a tree exists, because by then both are the same plain
113
+ string.
114
+
115
+ **Bound props are still translated** — that is the whole point of the suffix
116
+ rule, where a query manufactures a word and a read puts it on screen. There the
117
+ key is what protects data.
118
+
119
+ ## Counted phrases
120
+
121
+ A dictionary can hold "Standing". It can never hold "12 of 20" — two numbers
122
+ make the cardinality unbounded. What a book *can* hold is the **pattern**:
123
+
124
+ ```ts
125
+ { phrase: '{n} of {total}', slots: { n: 12, total: 20 } }
126
+ ```
127
+
128
+ At a prose key, the renderer translates the pattern string whole and then closes
129
+ the holes. Whole-pattern translation is what lets word order move — `{n} left`
130
+ becomes `noch {n}`, and the hole changes sides. A per-word table ("of" → "von")
131
+ starts at two entries and never stops growing.
132
+
133
+ A **string** slot is offered to the book too, so a composed sentence and its
134
+ fragments are separate rows that each translate.
135
+
136
+ Holes close **in every language, including the source one**, so no component
137
+ ever meets the raw `{ phrase, slots }` shape. Withdrawing a book means the
138
+ source language, not switching i18n off — a shell is language-bearing from the
139
+ moment it is given a book or a key set.
140
+
141
+ For a pattern held as data rather than shown — a check reading engine output, a
142
+ fixture, an exporter — use `fillPhrase(value)` from `@niscorp/nova/i18n`.
143
+
144
+ ## What this cannot do
145
+
146
+ - **Open-ended formatted values** — dates, money, counts. "Fri 14 Mar" has
147
+ unbounded cardinality and no dictionary will hold it. Format those at their
148
+ source with a locale (prism's `$localeDate`, `$localeMoney`, `$localeNumber`).
149
+ Note the axes differ: **words are per language, formatting is per region.**
150
+ One German book serves Vienna, Hamburg and Zürich; the same currency is
151
+ written three ways across them.
152
+ - **Anything not in the tree** — a server error message, a notification body, a
153
+ component's own hard-coded default copy. Default copy must be authored as a
154
+ prop, or the kit must translate it itself.
155
+
156
+ ## Changing the language at runtime
157
+
158
+ ```ts
159
+ shell.setPhrases(book); // reaches instances ALREADY mounted
160
+ shell.setPhrases(undefined); // back to the source language
161
+ shell.getPhrases(); // for overlaying rather than replacing
162
+ ```
163
+
164
+ A runtime asks for the book at each render rather than holding one from spawn,
165
+ so a screen that is already open switches with everything else. `setPhrases`
166
+ fires a state change, so mounted adapters re-render.
167
+
168
+ This reaches what nova renders. Text a **host** composed in the old language —
169
+ a greeting built in TypeScript, a seeded label — is the host's problem, and
170
+ usually means rebuilding.
171
+
172
+ ## Filling a dictionary: the harvest
173
+
174
+ Keying on source strings only works if there is a mechanical way to enumerate
175
+ them. Otherwise "translate the app" means a person reading every layout, and the
176
+ second language is permanently 90% done.
177
+
178
+ ```ts
179
+ import { harvestDefinitions, missingFrom } from '@niscorp/nova/i18n';
180
+
181
+ const found = harvestDefinitions(actions, phraseKeys);
182
+ const absent = missingFrom(found, book); // a release gate
183
+ ```
184
+
185
+ `harvestLayout` / `harvestDefinition` / `harvestDefinitions` walk the **authored
186
+ artifacts** — not a rendered tree — and return every phrase with every author
187
+ site. They reach:
188
+
189
+ - props at prose keys, at any depth, including inside `$if` / `$then` branches
190
+ - a layout's text children
191
+ - an action's `title` and its `data` defaults
192
+ - literals a trigger or lifecycle step **writes** into data — an error message a
193
+ trigger sets is as much product copy as a heading
194
+
195
+ Reading artifacts rather than a rendered tree is the second half of the
196
+ collision guard: only a string a person wrote can enter the dictionary, so a
197
+ value that happened to be on screen the day somebody ran the harvest cannot get
198
+ in.
199
+
200
+ At runtime, `onPhraseMiss(phrase, where)` reports every lookup that failed. A
201
+ miss renders as the **source language** — never an empty box, never a raw key —
202
+ which is the only sane failure and also the one that hides, so wire the report.
203
+
204
+ ## API
205
+
206
+ From `@niscorp/nova/i18n`:
207
+
208
+ | Export | Purpose |
209
+ |---|---|
210
+ | `harvestLayout` / `harvestDefinition` / `harvestDefinitions` | Enumerate the phrases an artifact can show |
211
+ | `missingFrom(harvested, book)` | What a language is still missing |
212
+ | `fillPhrase(value)` | Close a counted phrase held as data, outside a render |
213
+ | `translateRenderTree(tree, opts)` | For a tree you did **not** render — a replayed frame, a fixture |
214
+ | `DEFAULT_PHRASE_KEYS` | The default prose prop set |
215
+ | `isBinding` / `isPhrase` / `matcherFor` | The primitives the rules are built from |
216
+ | `Phrasebook` / `PhraseKeys` | Types |
217
+
218
+ Config fields: `phrases`, `phraseKeys`, `onPhraseMiss` on `ShellConfig`,
219
+ `RenderContext`, `RenderOptions` and `<Nova.Layout>`. Shell methods:
220
+ `setPhrases`, `getPhrases`.
221
+
222
+ **Both `phrases` and `phraseKeys` absent = not doing i18n**, and it costs
223
+ nothing: no matcher is built and a `{ phrase, slots }` passes through as the
224
+ object it is.