@x12i/fieldkit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 x12i
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# @x12i/fieldkit
+
+Metadata-driven React components for rendering structured records — markdown-derived
+report fields, pipeline output, whatever — as polished UI instead of a plain key/value
+dump. You own a small **rules map** (`field name -> how to render it`); fieldkit owns
+the **toolbox** of renderers those rules point at, plus a **shape-based fallback** for
+any field your map doesn't cover yet.
+
+Nothing in the package is domain-specific. Enum colors, which fields count as
+"content" vs. "diagnostics", and what counts as an attention-worthy state are all
+supplied by you — fieldkit just guarantees every field ends up rendered as *something*,
+never silently dropped.
+
+## Install
+
+```bash
+npm install @x12i/fieldkit
+```
+
+`react` and `react-dom` (>=18) are peer dependencies.
+
+## Quick start
+
+```tsx
+import { RecordView } from '@x12i/fieldkit';
+
+const record = {
+  status: 'REQUIRE_INFORMATION',
+  summary: 'This endpoint asset has no display name or usable address…',
+  highlights: ['Asset record is active…', 'Traffic observation coverage is complete…'],
+  riskSignals: ['Identity is unresolved…'],
+  openQuestions: ['What host, device, or endpoint corresponds to this source ID?'],
+  groundingStatus: 'INSUFFICIENT_EVIDENCE',
+  quality: 'EMPTY_MODEL',
+  stepId: 'triage-endpoint-asset',
+};
+
+const fieldRules = {
+  summary: { label: 'Summary', as: 'lead' },
+  highlights: { label: 'Highlights', as: 'bullets' },
+  riskSignals: { label: 'Risk Signals', as: 'signals' },
+  openQuestions: { label: 'Open Questions', as: 'qa' },
+  groundingStatus: { label: 'Grounding', as: 'pill' },
+  quality: { label: 'Quality', as: 'pill' },
+  stepId: { label: 'Step ID', as: 'mono' },
+};
+
+<RecordView
+  record={record}
+  fieldRules={fieldRules}
+  contentKeys={['summary', 'highlights', 'riskSignals', 'openQuestions']}
+  diagnosticKeys={['groundingStatus', 'quality', 'stepId']}
+  toneMap={{ REQUIRE_INFORMATION: 'amber', INSUFFICIENT_EVIDENCE: 'rose', EMPTY_MODEL: 'rose' }}
+/>;
+```
+
+See `examples/basic` in this repo for a full working page (header, banner rule, theming) —
+`npm run example` from the repo root.
+
+## The toolbox (`FieldKind`)
+
+| kind      | for                                         |
+|-----------|----------------------------------------------|
+| `lead`    | one prose paragraph, the primary read         |
+| `bullets` | array of short affirmative statements         |
+| `signals` | array of caution/warning statements (auto-classified warn vs. info) |
+| `qa`      | array of open questions                       |
+| `pill`    | a single enum-like value (status, quality…)   |
+| `mono`    | a short technical string (id, hash, code)     |
+| `text`    | plain secondary prose                         |
+| `flag`    | a boolean                                     |
+| `stat`    | a number                                      |
+| `tags`    | array of short tokens (not full sentences)    |
+| `empty`   | null / undefined / `''` — shown, not hidden   |
+| `json`    | anything else — pretty-printed as a fallback  |
+
+Every kind is handled in exactly one place (`FieldRenderer`'s switch), in both a
+`content` (full-weight) and `compact` (diagnostics/leftover) visual variant. The
+switch is exhaustive over the `FieldKind` union, so adding a new kind without wiring
+it up in `FieldRenderer` is a **compile error**, not a silently blank field.
+
+## Your rules map
+
+```ts
+export const fieldRules: FieldRules = {
+  summary: { label: 'Summary', as: 'lead' },
+  // ...
+};
+```
+
+Promoting a field out of the leftover bucket is a one-line addition here plus adding
+its key to `contentKeys` or `diagnosticKeys`.
+
+## Leftover handling
+
+Any key in `record` that isn't in `fieldRules` (or `identityKeys`) is resolved by
+`inferRule(key, value)`, which looks only at the **value's shape**:
+
+- `null` / `undefined` / `''` / `[]` → `empty`
+- `boolean` → `flag`
+- `number` → `stat`
+- `'ALL_CAPS_WITH_UNDERSCORES'` → `pill`
+- long prose / multi-sentence string → `lead`
+- short string with no spaces → `mono`
+- other string → `text`
+- array of questions (`?`-terminated) → `qa`
+- array of sentences → `bullets`
+- array of short tokens → `tags`
+- anything else (nested objects, arrays of objects) → `json`
+
+These render inside RecordView's diagnostics panel under "Additional Fields", clearly
+marked as unmapped, so a new field your pipeline starts emitting never disappears —
+it just isn't styled by hand yet.
+
+## Theming
+
+```tsx
+import { FieldKitProvider } from '@x12i/fieldkit';
+
+<FieldKitProvider
+  theme={{
+    colors: { accent: '#5B9BD5', background: '#0B0F14' },
+    fonts: { heading: 'Poppins, sans-serif', body: 'Inter, sans-serif' },
+  }}
+>
+  <RecordView {...} />
+</FieldKitProvider>;
+```
+
+Anything you don't override keeps `defaultTheme`. `RecordView` also works with no
+provider at all — it falls back to `defaultTheme` via context.
+
+Enum colors are a separate axis from the visual theme: pass `toneMap` (your enum
+value → tone name, e.g. `amber`/`rose`/`green`/`blue`/`violet`/`teal`) as a prop on
+`RecordView`. Anything not in your map still gets a deterministic color via
+`hashTone()` instead of falling back to gray every time.
+
+## Composable primitives
+
+`RecordView` is a default assembly of the pieces below — reach for them directly if
+you want a different layout:
+
+- `resolveField(key, value, rule, options)` — turn one field into a `ResolvedField`.
+- `inferRule(key, value)` — the leftover shape-inference function.
+- `FieldRenderer` — renders one `ResolvedField`.
+- `labelFromKey`, `defaultClassifySignal`, `hashTone`, `toneHex`, `TONE_PALETTE`.
+
+## Status
+
+`1.0.0` — first cut, ported from a design-canvas prototype. Known gaps to add next:
+a `group` kind for nested objects (currently falls into the `json` catch-all), and a
+richer default `classifySignal` (currently a 3-keyword heuristic — pass your own via
+the `classifySignal` prop until this improves).