@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.
- package/ACTION_DOCS.md +552 -0
- package/ADAPTER.md +170 -0
- package/DESIGN.md +719 -0
- package/I18N_DOCS.md +224 -0
- package/LAYOUT_DOCS.md +505 -0
- package/LICENSE +202 -0
- package/REACT_DOCS.md +562 -0
- package/README.md +379 -0
- package/SHELL_DOCS.md +615 -0
- package/TERMINAL_DOCS.md +124 -0
- package/dist/adapters/dom/components/index.cjs +473 -0
- package/dist/adapters/dom/components/index.cjs.map +1 -0
- package/dist/adapters/dom/components/index.d.cts +48 -0
- package/dist/adapters/dom/components/index.d.ts +48 -0
- package/dist/adapters/dom/components/index.js +420 -0
- package/dist/adapters/dom/components/index.js.map +1 -0
- package/dist/adapters/dom/index.cjs +171 -0
- package/dist/adapters/dom/index.cjs.map +1 -0
- package/dist/adapters/dom/index.d.cts +29 -0
- package/dist/adapters/dom/index.d.ts +29 -0
- package/dist/adapters/dom/index.js +15 -0
- package/dist/adapters/dom/index.js.map +1 -0
- package/dist/adapters/dom/server.cjs +129 -0
- package/dist/adapters/dom/server.cjs.map +1 -0
- package/dist/adapters/dom/server.d.cts +15 -0
- package/dist/adapters/dom/server.d.ts +15 -0
- package/dist/adapters/dom/server.js +37 -0
- package/dist/adapters/dom/server.js.map +1 -0
- package/dist/adapters/ink/index.d.ts +75 -0
- package/dist/adapters/ink/index.js +472 -0
- package/dist/adapters/ink/index.js.map +1 -0
- package/dist/adapters/react/components/index.cjs +552 -0
- package/dist/adapters/react/components/index.cjs.map +1 -0
- package/dist/adapters/react/components/index.d.cts +30 -0
- package/dist/adapters/react/components/index.d.ts +30 -0
- package/dist/adapters/react/components/index.js +12 -0
- package/dist/adapters/react/components/index.js.map +1 -0
- package/dist/adapters/react/index.cjs +1526 -0
- package/dist/adapters/react/index.cjs.map +1 -0
- package/dist/adapters/react/index.d.cts +149 -0
- package/dist/adapters/react/index.d.ts +149 -0
- package/dist/adapters/react/index.js +12 -0
- package/dist/adapters/react/index.js.map +1 -0
- package/dist/adapters/tty/components/index.cjs +255 -0
- package/dist/adapters/tty/components/index.cjs.map +1 -0
- package/dist/adapters/tty/components/index.d.cts +40 -0
- package/dist/adapters/tty/components/index.d.ts +40 -0
- package/dist/adapters/tty/components/index.js +187 -0
- package/dist/adapters/tty/components/index.js.map +1 -0
- package/dist/adapters/tty/index.cjs +76 -0
- package/dist/adapters/tty/index.cjs.map +1 -0
- package/dist/adapters/tty/index.d.cts +47 -0
- package/dist/adapters/tty/index.d.ts +47 -0
- package/dist/adapters/tty/index.js +76 -0
- package/dist/adapters/tty/index.js.map +1 -0
- package/dist/adapters/vue/components/index.cjs +619 -0
- package/dist/adapters/vue/components/index.cjs.map +1 -0
- package/dist/adapters/vue/components/index.d.cts +224 -0
- package/dist/adapters/vue/components/index.d.ts +224 -0
- package/dist/adapters/vue/components/index.js +12 -0
- package/dist/adapters/vue/components/index.js.map +1 -0
- package/dist/adapters/vue/index.cjs +747 -0
- package/dist/adapters/vue/index.cjs.map +1 -0
- package/dist/adapters/vue/index.d.cts +98 -0
- package/dist/adapters/vue/index.d.ts +98 -0
- package/dist/adapters/vue/index.js +127 -0
- package/dist/adapters/vue/index.js.map +1 -0
- package/dist/agent/index.cjs +178 -0
- package/dist/agent/index.cjs.map +1 -0
- package/dist/agent/index.d.cts +28 -0
- package/dist/agent/index.d.ts +28 -0
- package/dist/agent/index.js +30 -0
- package/dist/agent/index.js.map +1 -0
- package/dist/chunk-2MNLEL45.js +47 -0
- package/dist/chunk-2MNLEL45.js.map +1 -0
- package/dist/chunk-3HGE3VWK.js +753 -0
- package/dist/chunk-3HGE3VWK.js.map +1 -0
- package/dist/chunk-4ZID7UX5.js +549 -0
- package/dist/chunk-4ZID7UX5.js.map +1 -0
- package/dist/chunk-7B3RDENH.js +1982 -0
- package/dist/chunk-7B3RDENH.js.map +1 -0
- package/dist/chunk-7S5BNPUS.js +54 -0
- package/dist/chunk-7S5BNPUS.js.map +1 -0
- package/dist/chunk-7TS3YVQR.js +114 -0
- package/dist/chunk-7TS3YVQR.js.map +1 -0
- package/dist/chunk-EG2RUXJN.js +266 -0
- package/dist/chunk-EG2RUXJN.js.map +1 -0
- package/dist/chunk-GVBBL36G.js +429 -0
- package/dist/chunk-GVBBL36G.js.map +1 -0
- package/dist/chunk-I5D2R5UA.js +753 -0
- package/dist/chunk-I5D2R5UA.js.map +1 -0
- package/dist/chunk-IGLCWXQ3.js +304 -0
- package/dist/chunk-IGLCWXQ3.js.map +1 -0
- package/dist/chunk-JI7ZRESP.js +64 -0
- package/dist/chunk-JI7ZRESP.js.map +1 -0
- package/dist/chunk-L5223LLX.js +31 -0
- package/dist/chunk-L5223LLX.js.map +1 -0
- package/dist/chunk-LA3BSEMX.js +1905 -0
- package/dist/chunk-LA3BSEMX.js.map +1 -0
- package/dist/chunk-OAMC6R6E.js +121 -0
- package/dist/chunk-OAMC6R6E.js.map +1 -0
- package/dist/chunk-OGD5CCMZ.js +62 -0
- package/dist/chunk-OGD5CCMZ.js.map +1 -0
- package/dist/chunk-PF4OJTYU.js +199 -0
- package/dist/chunk-PF4OJTYU.js.map +1 -0
- package/dist/chunk-PZ5AY32C.js +9 -0
- package/dist/chunk-PZ5AY32C.js.map +1 -0
- package/dist/chunk-RBU5PHN4.js +8 -0
- package/dist/chunk-RBU5PHN4.js.map +1 -0
- package/dist/chunk-RQB4PRPV.js +285 -0
- package/dist/chunk-RQB4PRPV.js.map +1 -0
- package/dist/chunk-V32EVEVM.js +464 -0
- package/dist/chunk-V32EVEVM.js.map +1 -0
- package/dist/chunk-ZITHBBF3.js +85 -0
- package/dist/chunk-ZITHBBF3.js.map +1 -0
- package/dist/devtools/index.cjs +1088 -0
- package/dist/devtools/index.cjs.map +1 -0
- package/dist/devtools/index.d.cts +33 -0
- package/dist/devtools/index.d.ts +33 -0
- package/dist/devtools/index.js +399 -0
- package/dist/devtools/index.js.map +1 -0
- package/dist/effects-CndX9K7D.d.cts +123 -0
- package/dist/effects-CndX9K7D.d.ts +123 -0
- package/dist/endpoints-CD-6Jl-H.d.ts +36 -0
- package/dist/endpoints-Dem-EdRx.d.cts +36 -0
- package/dist/i18n/index.cjs +299 -0
- package/dist/i18n/index.cjs.map +1 -0
- package/dist/i18n/index.d.cts +28 -0
- package/dist/i18n/index.d.ts +28 -0
- package/dist/i18n/index.js +180 -0
- package/dist/i18n/index.js.map +1 -0
- package/dist/index-CNfzSBe2.d.ts +93 -0
- package/dist/index-caZoXSwr.d.cts +93 -0
- package/dist/index.cjs +3723 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +144 -0
- package/dist/index.d.ts +144 -0
- package/dist/index.js +15 -0
- package/dist/index.js.map +1 -0
- package/dist/migrations/index.cjs +635 -0
- package/dist/migrations/index.cjs.map +1 -0
- package/dist/migrations/index.d.cts +97 -0
- package/dist/migrations/index.d.ts +97 -0
- package/dist/migrations/index.js +50 -0
- package/dist/migrations/index.js.map +1 -0
- package/dist/palette-CP0wd3bE.d.ts +15 -0
- package/dist/palette-lm0bU9i5.d.cts +15 -0
- package/dist/primitive-props-BH_EJWIe.d.cts +100 -0
- package/dist/primitive-props-BH_EJWIe.d.ts +100 -0
- package/dist/primitive-props-CGoJvmcH.d.cts +100 -0
- package/dist/primitive-props-CGoJvmcH.d.ts +100 -0
- package/dist/reflect/index.cjs +998 -0
- package/dist/reflect/index.cjs.map +1 -0
- package/dist/reflect/index.d.cts +125 -0
- package/dist/reflect/index.d.ts +125 -0
- package/dist/reflect/index.js +13 -0
- package/dist/reflect/index.js.map +1 -0
- package/dist/schemas-DPdeFlCT.d.cts +38 -0
- package/dist/schemas-DPdeFlCT.d.ts +38 -0
- package/dist/schemas-pMyyuXV7.d.cts +47 -0
- package/dist/schemas-pMyyuXV7.d.ts +47 -0
- package/dist/types-Boh9ckdG.d.ts +194 -0
- package/dist/types-Brc7v_pS.d.ts +198 -0
- package/dist/types-ByNSwtUV.d.cts +20 -0
- package/dist/types-DdltMfw7.d.ts +20 -0
- package/dist/types-De0KpxfI.d.cts +198 -0
- package/dist/types-DhHL0twe.d.ts +20 -0
- package/dist/types-Dv6JLmgo.d.cts +194 -0
- package/dist/types-Q80YtOQt.d.cts +20 -0
- 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.
|