@visns-studio/visns-components 6.21.0 → 6.23.1

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/components/vault/VaultShareModal.jsx

@@ -1,6 +1,15 @@
 import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { toast } from 'react-toastify';
-import { Check, Copy, Link2, Loader2, ShieldAlert, Trash2 } from 'lucide-react';
+import {
+    AlertTriangle,
+    Check,
+    Copy,
+    Link2,
+    Loader2,
+    Mail,
+    ShieldAlert,
+    Trash2,
+} from 'lucide-react';
 
 import CustomFetch from '../Fetch';
 import StandardModal from '../generic/StandardModal';
@@ -14,6 +23,8 @@ import {
     availableShareFields,
     initialShareFields,
     isShareRevocable,
+    shareEmailEnabled,
+    shareEmailIssue,
     shareFieldsLabel,
     shareRequestBody,
     shareStatus,
@@ -51,6 +62,19 @@ const STATUS_CLASS = {
  * the recipient reveals — never the seed. That is said on the checkbox, not
  * just in this comment, because it is the one thing about this dialog a person
  * could reasonably get wrong.
+ *
+ * EMAILING THE LINK is optional and changes none of the above. The server sends
+ * it at creation — the only moment the raw URL exists on that side — and the
+ * mail carries the entry's title, the link and its limits, never a value off
+ * the credential. Two consequences show up in this file:
+ *
+ *  - The URL is still shown here, always, exactly as before. An email is a
+ *    delivery, not a substitute for the one copy of the link, and a send that
+ *    quietly failed must not take the credential with it — which is why the
+ *    server answers 201 with `email_error` rather than an error status, and why
+ *    the success panel below reports either outcome next to a copyable URL.
+ *  - Whether the field appears at all is the server's call, read from
+ *    `meta.email_enabled` on the share list this modal already fetches.
  */
 const VaultShareModal = ({ entry, endpoints, isOpen = true, onClose }) => {
     const routes = useMemo(() => resolveVaultEndpoints(endpoints), [endpoints]);
@@ -60,6 +84,12 @@ const VaultShareModal = ({ entry, endpoints, isOpen = true, onClose }) => {
     const [fields, setFields] = useState(() => initialShareFields(entry));
     const [expiresInHours, setExpiresInHours] = useState(DEFAULT_EXPIRY_HOURS);
     const [maxViews, setMaxViews] = useState(null);
+    const [recipient, setRecipient] = useState('');
+
+    // Whether the server will email at all. Optimistic until the list answers:
+    // a field that flickers away is better than one that never appears because
+    // a request was slow, and the server refuses a recipient it did not offer.
+    const [emailEnabled, setEmailEnabled] = useState(true);
 
     const [creating, setCreating] = useState(false);
     // The one and only copy of a freshly minted URL. Held in component state
@@ -97,6 +127,9 @@ const VaultShareModal = ({ entry, endpoints, isOpen = true, onClose }) => {
                 if (!mountedRef.current) return;
 
                 setShares(Array.isArray(result?.data) ? result.data : []);
+                // The one place this modal can learn its own configuration:
+                // the list request it was already making.
+                setEmailEnabled(shareEmailEnabled(result));
                 setLoading(false);
             },
             null
@@ -120,6 +153,11 @@ const VaultShareModal = ({ entry, endpoints, isOpen = true, onClose }) => {
 
     const toggle = (key) => setFields((current) => toggleShareField(current, key));
 
+    // A typo caught here is a sentence under the field; the same typo caught by
+    // the server is a 422 — and the server validates before it mints, so no
+    // link is lost either way. This is politeness, not a control.
+    const emailIssue = emailEnabled ? shareEmailIssue(recipient) : null;
+
     const create = useCallback(() => {
         if (!entry?.id || fields.length === 0) return;
 
@@ -128,7 +166,15 @@ const VaultShareModal = ({ entry, endpoints, isOpen = true, onClose }) => {
         CustomFetch(
             routes.createShare(entry.id),
             'POST',
-            shareRequestBody({ fields, expiresInHours, maxViews }),
+            shareRequestBody({
+                fields,
+                expiresInHours,
+                maxViews,
+                // Never sent when the server said it does not email, so a
+                // stale tab cannot post a recipient into an installation that
+                // has switched it off.
+                recipientEmail: emailEnabled ? recipient : '',
+            }),
             (result) => {
                 if (!mountedRef.current) return;
 
@@ -150,7 +196,16 @@ const VaultShareModal = ({ entry, endpoints, isOpen = true, onClose }) => {
             // server's "this entry has no password to share".
             if (mountedRef.current) setCreating(false);
         });
-    }, [routes, entry, fields, expiresInHours, maxViews, load]);
+    }, [
+        routes,
+        entry,
+        fields,
+        expiresInHours,
+        maxViews,
+        recipient,
+        emailEnabled,
+        load,
+    ]);
 
     const copyUrl = useCallback(async () => {
         if (!created?.url) return;
@@ -240,6 +295,29 @@ const VaultShareModal = ({ entry, endpoints, isOpen = true, onClose }) => {
                             </button>
                         </div>
 
+                        {created.emailed_to && (
+                            <p className={styles.shareEmailed}>
+                                <Mail size={14} strokeWidth={2.2} aria-hidden="true" />
+                                <span>
+                                    Also emailed to{' '}
+                                    <strong>{created.emailed_to}</strong>. The
+                                    email carries this link and the entry's
+                                    title — none of the details themselves.
+                                </span>
+                            </p>
+                        )}
+
+                        {created.email_error && (
+                            <p className={styles.shareEmailFailed} role="alert">
+                                <AlertTriangle
+                                    size={14}
+                                    strokeWidth={2.2}
+                                    aria-hidden="true"
+                                />
+                                <span>{created.email_error}</span>
+                            </p>
+                        )}
+
                         <p className={styles.shareWarning}>
                             <ShieldAlert size={14} strokeWidth={2.2} aria-hidden="true" />
                             <span>
@@ -259,6 +337,10 @@ const VaultShareModal = ({ entry, endpoints, isOpen = true, onClose }) => {
                                 onClick={() => {
                                     setCreated(null);
                                     setCopied(false);
+                                    // A second link almost never goes to the
+                                    // same person, and a left-over address is
+                                    // how one quietly does.
+                                    setRecipient('');
                                 }}
                             >
                                 Create another
@@ -361,17 +443,56 @@ const VaultShareModal = ({ entry, endpoints, isOpen = true, onClose }) => {
                             </p>
                         </div>
 
+                        {emailEnabled && (
+                            <div className={styles.field}>
+                                <label
+                                    className={styles.label}
+                                    htmlFor="vault-share-recipient"
+                                >
+                                    Email the link to (optional)
+                                </label>
+                                <input
+                                    id="vault-share-recipient"
+                                    type="email"
+                                    className={styles.input}
+                                    value={recipient}
+                                    placeholder="name@example.com"
+                                    autoComplete="off"
+                                    spellCheck="false"
+                                    onChange={(e) => setRecipient(e.target.value)}
+                                />
+                                {emailIssue ? (
+                                    <p className={styles.fieldError}>{emailIssue}</p>
+                                ) : (
+                                    <p className={styles.help}>
+                                        Sent when you create the link. The email
+                                        carries the link and this entry's title —
+                                        never the username, password or code. You
+                                        still get the link here to copy.
+                                    </p>
+                                )}
+                            </div>
+                        )}
+
                         <div className={styles.formActions}>
                             <button
                                 type="button"
                                 className={styles.primaryButton}
                                 onClick={create}
-                                disabled={creating || fields.length === 0}
+                                disabled={
+                                    creating ||
+                                    fields.length === 0 ||
+                                    Boolean(emailIssue)
+                                }
                             >
                                 {creating && (
                                     <Loader2 size={15} className={styles.spin} />
                                 )}
-                                {creating ? 'Creating…' : 'Create link'}
+                                {creating
+                                    ? 'Creating…'
+                                    : recipient.trim() !== '' && emailEnabled
+                                      ? 'Create and email link'
+                                      : 'Create link'}
                             </button>
                             <button
                                 type="button"

package/src/components/vault/vaultShares.js

@@ -131,17 +131,69 @@ export const toggleShareField = (fields, key) => {
     return known.filter((field) => next.includes(field));
 };
 
+/**
+ * Whether this installation will email a link for the sender.
+ *
+ * Read off the share LIST response, which the modal already fetches when it
+ * opens — a second request to learn one boolean would be a round trip for
+ * nothing. Defaults to true when the key is absent, so a build talking to a
+ * server that predates the flag offers the field and lets the server refuse,
+ * rather than hiding a feature that is switched on.
+ *
+ * @param {object} listResponse the payload from `endpoints.shares(id)`
+ * @returns {boolean}
+ */
+export const shareEmailEnabled = (listResponse) => {
+    const flag = listResponse?.meta?.email_enabled;
+
+    return flag === undefined || flag === null ? true : Boolean(flag);
+};
+
+/**
+ * What is wrong with the typed recipient address, or null.
+ *
+ * Deliberately the loosest check that still catches a typo — something, an @,
+ * something with a dot in it. The server validates properly and is the only
+ * opinion that counts; this exists so that a mistyped address is a sentence
+ * under the field rather than a 422 toast after the link has already been
+ * minted.
+ *
+ * @param {string} value
+ * @returns {(string|null)}
+ */
+export const shareEmailIssue = (value) => {
+    const address = String(value ?? '').trim();
+
+    if (address === '') return null;
+
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(address)
+        ? null
+        : 'That does not look like an email address.';
+};
+
 /**
  * The body the create endpoint wants.
  *
  * `max_views` is omitted rather than sent as null when there is no limit: the
  * server treats an absent key and a null the same way, and a body that carries
- * only what was chosen is easier to read in a network panel.
+ * only what was chosen is easier to read in a network panel. `recipient_email`
+ * is omitted the same way when nobody is being mailed — a create request with
+ * no recipient key in it is a create request that cannot possibly send mail,
+ * which is worth being able to read off a network panel at a glance.
+ *
+ * A recipient name is only sent alongside an address: it is the greeting on the
+ * email and means nothing without one.
  *
- * @param {{fields: Array<string>, expiresInHours: number, maxViews: (number|null)}} choice
+ * @param {{fields: Array<string>, expiresInHours: number, maxViews: (number|null), recipientEmail?: string, recipientName?: string}} choice
  * @returns {object}
  */
-export const shareRequestBody = ({ fields, expiresInHours, maxViews } = {}) => {
+export const shareRequestBody = ({
+    fields,
+    expiresInHours,
+    maxViews,
+    recipientEmail,
+    recipientName,
+} = {}) => {
     const known = SHARE_FIELDS.map((field) => field.key);
     const clean = known.filter((field) => (fields || []).includes(field));
 
@@ -160,6 +212,18 @@ export const shareRequestBody = ({ fields, expiresInHours, maxViews } = {}) => {
         body.max_views = Math.round(views);
     }
 
+    const address = String(recipientEmail ?? '').trim();
+
+    if (address !== '') {
+        body.recipient_email = address;
+
+        const name = String(recipientName ?? '').trim();
+
+        if (name !== '') {
+            body.recipient_name = name;
+        }
+    }
+
     return body;
 };