@visns-studio/visns-components 6.23.0 → 6.23.1

package/package.json

@@ -93,7 +93,7 @@
         "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0"
     },
     "name": "@visns-studio/visns-components",
-    "version": "6.23.0",
+    "version": "6.23.1",
     "description": "Various packages to assist in the development of our Custom Applications.",
     "main": "src/index.js",
     "files": [

package/src/components/JsonView.jsx

@@ -0,0 +1,299 @@
+import React, { useMemo, useState } from 'react';
+
+import styles from './styles/JsonView.module.scss';
+
+/**
+ * Where a string stops being a value and starts being a document.
+ *
+ * Exported because the truncation is observable — a caller that wants to know
+ * whether a field will be cut before it renders should ask the same number the
+ * component uses rather than restate it.
+ */
+export const STRING_PREVIEW_LIMIT = 200;
+
+/**
+ * Parse text that MIGHT be JSON, and answer only for the shapes worth drawing.
+ *
+ * `JSON.parse` is happy with `42`, `"a note"` and `true` — all three are valid
+ * JSON documents by the letter of the spec, and all three are also exactly what
+ * an ordinary hand-typed note looks like. Rendering "a note" as a one-row tree
+ * with a quoted string in it is worse than rendering the note, so a bare
+ * primitive is deliberately NOT JSON for this purpose: only an object or an
+ * array earns the tree.
+ *
+ * Returns the parsed value, or `null` for anything else — including the empty
+ * string, which parses as nothing at all.
+ *
+ * @param   {string} text  Raw text, leading and trailing space included.
+ * @returns {object|Array|null}
+ */
+export const parseJsonDocument = (text) => {
+    const trimmed = String(text ?? '').trim();
+
+    // Cheap gate before the parse. A 32KB note that is plainly prose should
+    // not cost a parse on every keystroke of the field above it.
+    if (trimmed === '' || !/^[{[]/.test(trimmed)) return null;
+
+    try {
+        const parsed = JSON.parse(trimmed);
+
+        return parsed !== null && typeof parsed === 'object' ? parsed : null;
+    } catch (error) {
+        // Not JSON, which is an answer rather than a failure.
+        return null;
+    }
+};
+
+/** An object or an array — the two things that get a collapse toggle. */
+const isContainer = (value) => value !== null && typeof value === 'object';
+
+const childEntries = (value) =>
+    Array.isArray(value)
+        ? value.map((item, index) => [index, item])
+        : Object.entries(value);
+
+/**
+ * What a collapsed node says about itself.
+ *
+ * The count is the whole point: `{…}` alone tells the reader nothing about
+ * whether opening it is worth the scroll, and `[…] 129 items` tells them
+ * everything.
+ */
+const summarise = (value) => {
+    const count = Array.isArray(value) ? value.length : Object.keys(value).length;
+    const noun = Array.isArray(value) ? 'item' : 'key';
+
+    return `${Array.isArray(value) ? '[…]' : '{…}'} ${count} ${noun}${
+        count === 1 ? '' : 's'
+    }`;
+};
+
+/** `{}` / `[]`, for a container with nothing in it to expand. */
+const emptyLiteral = (value) => (Array.isArray(value) ? '[]' : '{}');
+
+/**
+ * A string value, which is the only primitive that can be too big to print.
+ *
+ * TWO reasons a string gets a toggle, and they are the same reason:
+ *
+ *   It is long. 200 characters is about a line and a half here; past that the
+ *   value stops being something you read in passing and starts pushing the rest
+ *   of the document off the screen.
+ *
+ *   It has newlines in it. This is the case that matters for the vault: a
+ *   credentials backup keeps the actual credential in a `content` field with
+ *   embedded line breaks, so squashing it onto one line destroys the only
+ *   structure it has. A multi-line string is therefore treated as long even
+ *   when it is short, and the expanded form is `pre-wrap`.
+ *
+ * The collapsed form is deliberately one line — first line, cut to the limit —
+ * because a preview that reflows is not a preview.
+ */
+const JsonString = ({ value }) => {
+    const [open, setOpen] = useState(false);
+
+    const multiline = value.includes('\n');
+    const long = value.length > STRING_PREVIEW_LIMIT;
+
+    if (!multiline && !long) {
+        return <span className={styles.string}>"{value}"</span>;
+    }
+
+    if (open) {
+        return (
+            <span className={styles.valueCell}>
+                <span className={`${styles.string} ${styles.stringOpen}`}>
+                    "{value}"
+                </span>
+                <button
+                    type="button"
+                    className={styles.more}
+                    onClick={() => setOpen(false)}
+                >
+                    show less
+                </button>
+            </span>
+        );
+    }
+
+    const firstLine = value.split('\n', 1)[0];
+    const preview =
+        firstLine.length > STRING_PREVIEW_LIMIT
+            ? firstLine.slice(0, STRING_PREVIEW_LIMIT)
+            : firstLine;
+
+    return (
+        <span className={styles.valueCell}>
+            <span className={styles.string}>"{preview}…"</span>
+            <button
+                type="button"
+                className={styles.more}
+                onClick={() => setOpen(true)}
+                title={
+                    multiline
+                        ? `${value.split('\n').length} lines, ${value.length} characters`
+                        : `${value.length} characters`
+                }
+            >
+                show all
+            </button>
+        </span>
+    );
+};
+
+/** Everything that is not a container: tinted by type, so the type is readable. */
+const JsonPrimitive = ({ value }) => {
+    if (value === null) return <span className={styles.null}>null</span>;
+
+    switch (typeof value) {
+        case 'string':
+            return <JsonString value={value} />;
+        case 'number':
+            // `String()` rather than the raw number so NaN and Infinity print
+            // as themselves: neither can come out of JSON.parse, but this
+            // component takes an already-parsed value from anywhere.
+            return <span className={styles.number}>{String(value)}</span>;
+        case 'boolean':
+            return <span className={styles.boolean}>{value ? 'true' : 'false'}</span>;
+        case 'undefined':
+            return <span className={styles.null}>undefined</span>;
+        default:
+            // A function or a symbol, which only a hand-built value can carry.
+            return <span className={styles.null}>{String(value)}</span>;
+    }
+};
+
+/**
+ * One row: a key, and either a value or a subtree behind a toggle.
+ *
+ * The toggle is a real `<button>` wrapping the caret, the key AND the summary,
+ * so the hit target is the whole line and there is one tab stop per node rather
+ * than one per glyph. There is no `role="tree"` here on purpose: that role
+ * promises arrow-key navigation, and a tree that does not answer arrow keys is
+ * worse for a screen reader than the plain nested list this actually is.
+ */
+const JsonNode = ({ label, isIndex, value, depth, collapsedDepth }) => {
+    const container = isContainer(value);
+    const entries = useMemo(
+        () => (container ? childEntries(value) : []),
+        [container, value]
+    );
+
+    // The root is depth 0, so `collapsedDepth: 2` opens the root and its
+    // children and collapses everything from the grandchildren down. On the
+    // vault's backup payload that is exactly right: the document and its
+    // `credentials` array are open, and the 129 credentials inside it are 129
+    // one-line summaries rather than 129 open records.
+    const [open, setOpen] = useState(depth < collapsedDepth);
+
+    const key = label === null ? null : (
+        <span className={isIndex ? styles.index : styles.key}>
+            {String(label)}
+            <span className={styles.colon}>:</span>
+        </span>
+    );
+
+    if (!container || entries.length === 0) {
+        return (
+            <li className={styles.row}>
+                <div className={styles.line}>
+                    <span className={styles.spacer} aria-hidden="true" />
+                    {key}
+                    {container ? (
+                        <span className={styles.summary}>{emptyLiteral(value)}</span>
+                    ) : (
+                        <JsonPrimitive value={value} />
+                    )}
+                </div>
+            </li>
+        );
+    }
+
+    return (
+        <li className={styles.row}>
+            <div className={styles.line}>
+                <button
+                    type="button"
+                    className={styles.toggle}
+                    aria-expanded={open}
+                    onClick={() => setOpen((v) => !v)}
+                >
+                    <span className={styles.caret} aria-hidden="true">
+                        {open ? '▾' : '▸'}
+                    </span>
+                    {key}
+                    <span className={styles.summary}>
+                        {open ? (Array.isArray(value) ? '[' : '{') : summarise(value)}
+                    </span>
+                </button>
+            </div>
+
+            {open && (
+                <>
+                    <ul className={`${styles.list} ${styles.children}`}>
+                        {entries.map(([childLabel, childValue]) => (
+                            <JsonNode
+                                key={String(childLabel)}
+                                label={childLabel}
+                                isIndex={Array.isArray(value)}
+                                value={childValue}
+                                depth={depth + 1}
+                                collapsedDepth={collapsedDepth}
+                            />
+                        ))}
+                    </ul>
+                    {/* The closing bracket, so an open node reads as a pair
+                        rather than as a bracket somebody forgot to shut. */}
+                    <div className={styles.line}>
+                        <span className={styles.spacer} aria-hidden="true" />
+                        <span className={styles.summary}>
+                            {Array.isArray(value) ? ']' : '}'}
+                        </span>
+                    </div>
+                </>
+            )}
+        </li>
+    );
+};
+
+/**
+ * A parsed JSON value, as something a person can actually read.
+ *
+ * Written for the vault's notes, where `zoho:credentials-backup` leaves a
+ * 32KB machine-written blob — `{source, account_id, …, credentials: […]}` — in
+ * a field whose only previous rendering was a three-row textarea. Nothing in
+ * here knows that, and nothing should: it takes a value and draws it.
+ *
+ * READ-ONLY, and that is the design rather than an omission. Editing JSON as a
+ * tree means deciding what happens when a key is renamed to one that already
+ * exists, what a number that is being typed means halfway through, and what to
+ * do with a value the user has made syntactically impossible. The consumer
+ * keeps the raw text as the single source of truth and toggles between the two;
+ * see VaultEntryForm, where the notes VALUE is always the raw string and this
+ * view is presentation only.
+ *
+ * The value is passed ALREADY PARSED. A component that took text would have to
+ * decide what a parse failure looks like on screen, and the answer is always
+ * "show the text instead", which is a decision belonging to the screen and not
+ * to the viewer. `parseJsonDocument` above is the shared way to make that call.
+ *
+ * @param {*}      value           Any parsed JS value; objects and arrays get a tree.
+ * @param {number} collapsedDepth  Nodes at this depth or deeper start collapsed.
+ *                                 The root is depth 0. Default 2.
+ * @param {string} className       Added to the root, for sizing by the caller.
+ */
+const JsonView = ({ value, collapsedDepth = 2, className, ...rest }) => (
+    <div className={[styles.root, className].filter(Boolean).join(' ')} {...rest}>
+        <ul className={styles.list}>
+            <JsonNode
+                label={null}
+                isIndex={false}
+                value={value}
+                depth={0}
+                collapsedDepth={collapsedDepth}
+            />
+        </ul>
+    </div>
+);
+
+export default JsonView;

package/src/components/styles/JsonView.module.scss

@@ -0,0 +1,233 @@
+@use 'surface' as *;
+
+/**
+ * JsonView — a parsed JSON value drawn as a collapsible tree.
+ *
+ * The palette is the page-primitive one (`_surface.scss`): two levels, so a
+ * project that defines nothing gets something legible and a page that already
+ * has a palette sets `--vs-*` once on its own root. Nothing here carries a
+ * colour of its own except the four type tints, and even those are mixed
+ * against the app's body ink rather than declared outright — see below.
+ *
+ * Sizing is the CALLER's job. The root has no height, no scroll and no border:
+ * a tree inside a modal wants a capped scroll region, the same tree on a page
+ * wants to be as tall as it is, and a component that decides that itself is one
+ * the next screen has to fight.
+ */
+
+$jv-mono: 'SFMono-Regular', 'Menlo', 'Consolas', monospace;
+
+.root {
+    @include surface-tokens;
+
+    /**
+     * The type tints, and why each is a MIX rather than a hex value.
+     *
+     * A JSON viewer needs four inks that are distinguishable from each other
+     * and readable on the page behind them — and this library does not know
+     * which page that is. A fixed `#1f8b4c` is a fine green on white and an
+     * unreadable one on a dark surface.
+     *
+     * Mixing the hue with the app's own body ink solves both directions at
+     * once: on a light theme the ink is near-black, so the hue darkens and
+     * gains contrast against white; on a dark theme the ink is near-white, so
+     * the SAME declaration lightens it against the dark ground. The hue stays
+     * recognisable either way because it is three quarters of the mix.
+     */
+    --jv-key: var(--vs-json-key, color-mix(in srgb, var(--pr-heading) 80%, var(--pr-ink)));
+    --jv-string: var(--vs-json-string, color-mix(in srgb, #1f8b4c 74%, var(--pr-ink)));
+    --jv-number: var(--vs-json-number, color-mix(in srgb, #2f6fd0 74%, var(--pr-ink)));
+    --jv-boolean: var(
+        --vs-json-boolean,
+        color-mix(in srgb, #8a5cd0 74%, var(--pr-ink))
+    );
+    // The indent guide is a hairline that must read as structure and not as a
+    // border; the page's own line colour is too heavy repeated every level.
+    --jv-guide: var(--vs-json-guide, color-mix(in srgb, var(--pr-ink) 16%, transparent));
+
+    color: var(--pr-ink);
+    font-family: $jv-mono;
+    // Small and tight: the value of this view over a textarea is how much of
+    // the document fits on one screen.
+    font-size: 0.76rem;
+    line-height: 1.45;
+    text-align: left;
+    // A long unbroken token — a URL, a base64 blob — must wrap rather than
+    // push a horizontal scrollbar under the whole tree.
+    overflow-wrap: anywhere;
+}
+
+/* The size is declared on the elements as well as the root: inherited
+   font-size loses to ANY rule that names the element directly, however
+   specific the ancestor — and this tree mounts inside host apps whose global
+   stylesheets do exactly that to li, span and button. Restating `inherit`
+   here puts a declaration on every element, outranking a host's bare
+   element rules (0-0-1 vs this 0-1-0). `:where()` keeps the inner selector
+   at zero so the file's own later, smaller sizes (`.more`) still win. */
+.root :where(ul, li, span, button) {
+    font-family: inherit;
+    font-size: inherit;
+    line-height: inherit;
+}
+
+.list {
+    padding: 0;
+    margin: 0;
+    list-style: none;
+}
+
+/* Each level is indented by its own guide line, so the depth is readable
+   without counting spaces. */
+.children {
+    padding-left: 0.7rem;
+    margin-left: 0.28rem;
+    border-left: 1px solid var(--jv-guide);
+}
+
+.row {
+    // The host CRM styles bare list items in places; nothing here inherits
+    // anything it needs. Same reasoning as Vault.module.scss's header.
+    padding: 0;
+    margin: 0;
+    list-style: none;
+}
+
+.line {
+    display: flex;
+    gap: 0.3rem;
+    align-items: flex-start;
+    min-width: 0;
+}
+
+/* Sits under the caret of a node that has one, so keys line up whether or not
+   the row is expandable. */
+.spacer {
+    flex: 0 0 0.85rem;
+    width: 0.85rem;
+}
+
+.toggle {
+    display: inline-flex;
+    gap: 0.3rem;
+    align-items: flex-start;
+    box-sizing: border-box;
+    width: auto;
+    min-width: 0;
+    height: auto;
+    min-height: 0;
+    padding: 0 0.15rem 0 0;
+    margin: 0;
+    color: inherit;
+    font: inherit;
+    text-align: left;
+    text-transform: none;
+    letter-spacing: normal;
+    background: none;
+    border: 0;
+    border-radius: var(--pr-radius, 6px);
+    box-shadow: none;
+    cursor: pointer;
+    appearance: none;
+
+    &:hover {
+        background: var(--pr-quiet);
+    }
+
+    &:focus-visible {
+        outline: 2px solid var(--pr-accent);
+        outline-offset: 1px;
+    }
+}
+
+.caret {
+    flex: 0 0 0.85rem;
+    width: 0.85rem;
+    color: var(--pr-muted);
+    /* The two glyphs have different optical widths; a fixed box stops the key
+       beside them shifting by a pixel on every open and close. */
+    text-align: left;
+}
+
+.key {
+    color: var(--jv-key);
+    font-weight: 600;
+}
+
+/* An array index is not a name, and painting it like one makes a long list look
+   like a hundred different keys. */
+.index {
+    color: var(--pr-muted);
+}
+
+.colon {
+    color: var(--pr-muted);
+    font-weight: 400;
+}
+
+/* `{…} 5 keys`, and the brackets of an open node. */
+.summary {
+    color: var(--pr-muted);
+}
+
+.valueCell {
+    display: inline-flex;
+    flex-wrap: wrap;
+    gap: 0.35rem;
+    align-items: baseline;
+    min-width: 0;
+}
+
+.string {
+    color: var(--jv-string);
+}
+
+/* The expanded form of a multi-line string. This is where the vault's
+   credentials actually live — a `content` field with embedded newlines — so the
+   line breaks are the content, not whitespace to be collapsed. */
+.stringOpen {
+    display: block;
+    white-space: pre-wrap;
+}
+
+.number {
+    color: var(--jv-number);
+    font-variant-numeric: tabular-nums;
+}
+
+.boolean {
+    color: var(--jv-boolean);
+    font-weight: 600;
+}
+
+.null {
+    color: var(--pr-muted);
+    font-style: italic;
+}
+
+/* "show all" / "show less" on a truncated value. A link rather than a chip: it
+   sits inside a line of text and must not become the loudest thing on it. */
+.more {
+    box-sizing: border-box;
+    width: auto;
+    height: auto;
+    min-width: 0;
+    min-height: 0;
+    padding: 0;
+    margin: 0;
+    color: var(--pr-accent);
+    font: inherit;
+    font-size: 0.72rem;
+    text-decoration: underline;
+    text-transform: none;
+    letter-spacing: normal;
+    background: none;
+    border: 0;
+    box-shadow: none;
+    cursor: pointer;
+    appearance: none;
+
+    &:focus-visible {
+        outline: 2px solid var(--pr-accent);
+        outline-offset: 2px;
+    }
+}

package/src/components/styles/Vault.module.scss

@@ -1284,6 +1284,74 @@ input.checkControl {
     resize: vertical;
 }
 
+// ---------------------------------------------------------------------------
+// Notes: the Formatted / Raw toggle
+// ---------------------------------------------------------------------------
+// Notes holding a machine-written JSON backup are READ as a tree (JsonView) and
+// EDITED as text. Two chips rather than a switch, because a switch has to be
+// labelled with the state it is not in and there is no good way to word that
+// here; two chips name both and light the one you are looking at.
+
+.viewToggle {
+    display: inline-flex;
+    gap: 0.25rem;
+    align-self: flex-start;
+    padding: 0.15rem;
+    border: 1px solid var(--v-line);
+    border-radius: var(--v-btn-br);
+    background: var(--v-surface);
+}
+
+.viewChip {
+    @include vault-reset;
+    @include vault-focus;
+
+    display: inline-flex;
+    align-items: center;
+    padding: 0.2rem 0.55rem;
+    border: 1px solid transparent;
+    border-radius: calc(var(--v-btn-br) - 1px);
+    background: none;
+    color: var(--v-muted);
+    font-size: 0.72rem;
+    font-weight: 600;
+    letter-spacing: 0.02em;
+    cursor: pointer;
+
+    &:hover:not(:disabled) {
+        color: var(--v-primary);
+    }
+
+    // Disabled here means "the JSON is broken, so there is nothing to lay
+    // out"; the chip carries a title saying so. Dimmed rather than removed —
+    // a control that disappears takes its own explanation with it.
+    &:disabled {
+        cursor: default;
+        opacity: 0.45;
+    }
+}
+
+.viewChipOn {
+    border-color: var(--v-line);
+    background: var(--v-background);
+    color: var(--v-primary);
+}
+
+// The tree's container. JsonView declares no height of its own on purpose, so
+// the cap belongs here: 50vh keeps a 32KB backup scrolling inside the field
+// instead of pushing Save off the bottom of the dialog.
+.notesJson {
+    @include vault-focus;
+
+    box-sizing: border-box;
+    max-height: 50vh;
+    padding: 0.5rem 0.6rem;
+    overflow: auto;
+    border: 1px solid var(--v-line);
+    border-radius: var(--v-btn-br);
+    background: var(--v-surface);
+}
+
 .help {
     margin: 0;
     color: var(--v-muted);

package/src/components/vault/VaultEntryForm.jsx

@@ -13,6 +13,7 @@ import {
 } from 'lucide-react';
 
 import CustomFetch from '../Fetch';
+import JsonView, { parseJsonDocument } from '../JsonView';
 import StandardModal from '../generic/StandardModal';
 import styles from '../styles/Vault.module.scss';
 import PasswordGenerator from './PasswordGenerator';
@@ -41,6 +42,26 @@ const EMPTY = {
  * it. So the form tracks intent rather than value, and only puts a key in the
  * body when the user actually expressed one.
  *
+ * **Notes are the same rule for a different reason.** They are not secret, but
+ * they are encrypted and so are deliberately absent from the LIST row — and the
+ * list row is what opens this form. Seeding `notes` from it and then sending
+ * `notes: ""` back means every edit made from the list silently wipes whatever
+ * the entry held, which is how a 32KB machine-written backup can vanish behind
+ * a one-word title change. So an existing entry fetches its own detail payload
+ * when the form opens, and the `notes` key goes in the body only when there is
+ * an answer to send: always for a new entry, and for an existing one only once
+ * that fetch has succeeded. A fetch that failed omits the key entirely, which
+ * is the API's "leave it alone" — the rest of the form still saves.
+ *
+ * Once those notes are on screen they are often not prose at all:
+ * `zoho:credentials-backup` leaves a pretty-printed
+ * `{source, account_id, …, credentials: [{label, content}…]}` blob in the
+ * field, and reading 32KB of it through a three-row textarea is miserable. So
+ * notes that parse as a JSON object or array get a Formatted/Raw toggle and
+ * default to a collapsible tree (`JsonView`). It changes nothing about what is
+ * saved: the notes VALUE is the raw text either way, the tree is read-only, and
+ * every edit still happens in the textarea behind the Raw chip.
+ *
  * The 2FA field takes either a bare base32 secret or the whole `otpauth://`
  * link, and says what it understood — digits, period, algorithm — before the
  * entry is saved, because the failure mode otherwise is a code that is simply
@@ -104,12 +125,24 @@ const VaultEntryForm = ({
     const [dropping, setDropping] = useState(false);
     const qrFileRef = useRef(null);
 
+    // 'ready' (nothing to load — a new entry) | 'loading' | 'loaded' | 'failed'.
+    // Only 'ready' and 'loaded' are safe to assert intent from; see submit().
+    const [notesState, setNotesState] = useState(() =>
+        entry?.id ? 'loading' : 'ready'
+    );
+
     const [errors, setErrors] = useState({});
     const [saving, setSaving] = useState(false);
 
     const mountedRef = useRef(true);
     const titleRef = useRef(null);
 
+    // The entry id whose notes have already been asked for. A ref rather than a
+    // dependency because the fetch must happen once per open, not once per
+    // render — `routes` is rebuilt whenever the consumer passes a fresh
+    // `endpoints` object, and a keystroke must never cost a round trip.
+    const notesRequestedFor = useRef(null);
+
     useEffect(() => {
         mountedRef.current = true;
 
@@ -122,6 +155,115 @@ const VaultEntryForm = ({
         if (isOpen) setTimeout(() => titleRef.current?.focus(), 0);
     }, [isOpen]);
 
+    /* -------------------------------------------------------------- notes */
+
+    /**
+     * Fetch the entry's notes from the detail endpoint.
+     *
+     * The list row this form is opened from has no `notes` — the column is
+     * encrypted and loaded one entry at a time — so the only honest way to fill
+     * the field is to ask for the entry itself. The fetch lives here rather
+     * than in the list because this is the component that knows it is editing,
+     * and because the notes are of no use to a row that only draws a title.
+     *
+     * A failure is not toasted: it is not a failed action, it is a field that
+     * cannot be edited this time round. The submit path reads `notesState` and
+     * omits the key, so the stored notes survive the save either way.
+     *
+     * Note that the detail endpoint writes a `view` to the access log, so
+     * opening this form on an existing entry now leaves a row. That is correct
+     * rather than incidental — the notes are decrypted and put on screen, which
+     * is exactly what a `view` records.
+     */
+    const loadNotes = useCallback(() => {
+        if (!entry?.id) return;
+
+        setNotesState('loading');
+
+        CustomFetch(
+            routes.show(entry.id),
+            'GET',
+            null,
+            (result) => {
+                if (!mountedRef.current) return;
+
+                setValues((prev) => ({ ...prev, notes: result?.notes ?? '' }));
+                setNotesState('loaded');
+            },
+            // An errorCallback, empty on purpose: given one, CustomFetch stops
+            // toasting, which is the whole point.
+            () => {
+                if (!mountedRef.current) return;
+
+                setNotesState('failed');
+            }
+        ).catch(() => {
+            // Already handled above; swallowed so the rejection is not
+            // unhandled.
+        });
+    }, [entry?.id, routes]);
+
+    useEffect(() => {
+        if (!isOpen || !entry?.id) return;
+
+        // Once per open. Re-running on every render would refetch while the
+        // user types, and worse, would overwrite what they had typed.
+        if (notesRequestedFor.current === entry.id) return;
+
+        notesRequestedFor.current = entry.id;
+        loadNotes();
+    }, [isOpen, entry?.id, loadNotes]);
+
+    // Disabled while there is nothing trustworthy to edit: blank-and-editable
+    // reads as "this entry has no notes", which is the misunderstanding that
+    // wiped them in the first place.
+    const notesLocked = notesState === 'loading' || notesState === 'failed';
+
+    /* --------------------------------------------------- notes as a document */
+
+    // 'formatted' (the tree) | 'raw' (the textarea, and the only place editing
+    // happens). Presentation only — see submit(): the notes VALUE is the raw
+    // string in `values.notes` whichever of the two is on screen.
+    const [notesView, setNotesView] = useState('formatted');
+
+    /**
+     * The notes as a JSON document, or null if they are not one.
+     *
+     * `zoho:credentials-backup` writes up to 32KB of pretty-printed
+     * `{source, account_id, …, credentials: [{label, content}…]}` into this
+     * field, and a textarea three rows tall is a genuinely bad way to read it.
+     *
+     * Gated on `notesState` for the same reason submit() is: until the detail
+     * fetch has answered, `values.notes` is not the entry's notes — it is the
+     * empty string the form started with. Parsing that would be answering a
+     * question about a value we do not have yet. Because the gate reads the
+     * state, this re-runs by itself the moment the fetch lands, which is what
+     * makes the toggle appear on an entry opened from the list.
+     */
+    const notesDocument = useMemo(
+        () =>
+            notesState === 'ready' || notesState === 'loaded'
+                ? parseJsonDocument(values.notes)
+                : null,
+        [notesState, values.notes]
+    );
+
+    // Shown while the notes ARE a document — and also while the user is in the
+    // raw editor with something that is still trying to be one. That second
+    // case is the whole reason this is not just `Boolean(notesDocument)`: break
+    // a brace while editing and the toggle would otherwise vanish out from
+    // under the cursor, taking the way back with it. Instead it stays, with
+    // Formatted disabled and saying why. It cannot appear on ordinary prose,
+    // because reaching the raw editor at all requires the chips, which require
+    // a document.
+    const notesToggle =
+        Boolean(notesDocument) ||
+        (notesView === 'raw' && /^\s*[{[]/.test(values.notes || ''));
+
+    // The tree is only ever drawn for a document that parsed THIS render, so
+    // broken JSON falls back to the textarea rather than to a stale tree.
+    const notesFormatted = Boolean(notesDocument) && notesView === 'formatted';
+
     const set = (key, value) => {
         setValues((prev) => ({ ...prev, [key]: value }));
         setErrors((prev) => (prev[key] ? { ...prev, [key]: undefined } : prev));
@@ -266,7 +408,6 @@ const VaultEntryForm = ({
             title: values.title.trim(),
             url: (values.url || '').trim(),
             username: (values.username || '').trim(),
-            notes: values.notes || '',
             tags,
             visibility: values.visibility,
             // Always sent, including as null — that is how an entry gets
@@ -275,6 +416,15 @@ const VaultEntryForm = ({
         };
 
         // Key presence is the contract — see the note at the top of the file.
+
+        // Notes: sent whenever what is in the box is genuinely what the entry
+        // holds. For a new entry that is trivially true; for an existing one it
+        // is true only after the detail fetch answered. Anything else omits the
+        // key, and the API leaves the stored notes exactly where they were.
+        if (notesState === 'ready' || notesState === 'loaded') {
+            body.notes = values.notes || '';
+        }
+
         if (clearPassword) body.password = '';
         else if (password !== '') body.password = password;
 
@@ -694,13 +844,94 @@ const VaultEntryForm = ({
                 {field(
                     'notes',
                     'Notes',
-                    <textarea
-                        id="vault-notes"
-                        className={styles.textarea}
-                        rows={3}
-                        value={values.notes || ''}
-                        onChange={(e) => set('notes', e.target.value)}
-                    />
+                    <>
+                        {notesToggle && (
+                            <div
+                                className={styles.viewToggle}
+                                role="group"
+                                aria-label="Notes view"
+                            >
+                                <button
+                                    type="button"
+                                    className={`${styles.viewChip} ${
+                                        notesFormatted ? styles.viewChipOn : ''
+                                    }`}
+                                    aria-pressed={notesFormatted}
+                                    disabled={!notesDocument}
+                                    title={
+                                        notesDocument
+                                            ? undefined
+                                            : 'These notes are no longer valid JSON, so there is nothing to lay out — fix the syntax here and this comes back.'
+                                    }
+                                    onClick={() => setNotesView('formatted')}
+                                >
+                                    Formatted
+                                </button>
+                                <button
+                                    type="button"
+                                    className={`${styles.viewChip} ${
+                                        notesFormatted ? '' : styles.viewChipOn
+                                    }`}
+                                    aria-pressed={!notesFormatted}
+                                    onClick={() => setNotesView('raw')}
+                                >
+                                    Raw
+                                </button>
+                            </div>
+                        )}
+
+                        {notesFormatted ? (
+                            // Read-only, and capped so a 32KB backup scrolls
+                            // inside the field instead of pushing Save off the
+                            // bottom of the dialog.
+                            <div
+                                // The label above says "Notes"; keeping the id
+                                // here means it still points at what it names.
+                                // Focusable because a scroll region a mouse can
+                                // reach and a keyboard cannot is only half a
+                                // control.
+                                id="vault-notes"
+                                className={styles.notesJson}
+                                role="region"
+                                aria-label="Notes, laid out as JSON"
+                                tabIndex={0}
+                            >
+                                <JsonView value={notesDocument} />
+                            </div>
+                        ) : (
+                            <textarea
+                                id="vault-notes"
+                                className={styles.textarea}
+                                rows={3}
+                                value={values.notes || ''}
+                                disabled={notesLocked}
+                                placeholder={
+                                    notesState === 'loading' ? 'Loading notes…' : ''
+                                }
+                                onChange={(e) => set('notes', e.target.value)}
+                            />
+                        )}
+
+                        {notesFormatted && (
+                            <p className={styles.help}>
+                                These notes are JSON. Switch to Raw to edit them.
+                            </p>
+                        )}
+
+                        {notesState === 'failed' && (
+                            <p className={styles.fieldError} role="alert">
+                                The notes could not be loaded, so they cannot be
+                                edited here — saving will leave them as they are.{' '}
+                                <button
+                                    type="button"
+                                    className={styles.linkButton}
+                                    onClick={loadNotes}
+                                >
+                                    Try again
+                                </button>
+                            </p>
+                        )}
+                    </>
                 )}
 
                 {field(

package/src/components/vault/VaultManager.jsx

@@ -168,6 +168,18 @@ const VaultManagerInner = ({
      */
     clientId = null,
     clientLabel = null,
+    /**
+     * The order the list opens in, before anyone clicks a column header.
+     *
+     * The library's default stays most-recently-touched first — on a vault
+     * that is worked in, the entry someone just rotated is the one they are
+     * about to verify. A host whose vault is browsed rather than worked
+     * (looked through by name, like a phone book) passes 'title' / 'asc'.
+     * Clicking a header still overrides either way; this is only the opening
+     * state.
+     */
+    defaultSort = 'updated_at',
+    defaultDirection = 'desc',
 }) => {
     const routes = useMemo(() => resolveVaultEndpoints(endpoints), [endpoints]);
 
@@ -190,8 +202,8 @@ const VaultManagerInner = ({
     // production is one page in eight.
     const [clientOptions, setClientOptions] = useState([]);
     const [includeDeleted, setIncludeDeleted] = useState(false);
-    const [sort, setSort] = useState('updated_at');
-    const [direction, setDirection] = useState('desc');
+    const [sort, setSort] = useState(defaultSort);
+    const [direction, setDirection] = useState(defaultDirection);
     const [page, setPage] = useState(1);
     const [perPage, setPerPage] = useState(
         Number(perPageProp) > 0 ? Number(perPageProp) : PER_PAGE

package/src/index.js

@@ -47,6 +47,11 @@ import ImageModal from './components/ImageModal';
 import DatePickerPortal from './components/utils/DatePickerPortal';
 import NativeDateFilterEditor from './components/columns/NativeDateFilterEditor';
 import ImportWizardModal from './components/ImportWizardModal';
+// A parsed JSON value as a collapsible tree, plus the rule for deciding whether
+// some text is one worth drawing. Written for the vault's notes — a machine
+// written backup blob in a textarea is unreadable — but there is nothing
+// vault-specific in either half, so both live out here.
+import JsonView, { parseJsonDocument, STRING_PREVIEW_LIMIT } from './components/JsonView';
 export * from './components/columns/ColumnRenderers.jsx';
 
 /** Auth Specific Components */
@@ -479,6 +484,9 @@ export {
     ImportWizardModal,
     isCompleteOtp,
     isSuccessBody,
+    JsonView,
+    parseJsonDocument,
+    STRING_PREVIEW_LIMIT,
     Loader,
     Login,
     LogoutScreen,