@visns-studio/visns-components 6.32.3 → 6.34.3

package/src/components/auth/passkeyClient.js

@@ -0,0 +1,102 @@
+/**
+ * The three authenticated passkey requests, written once.
+ *
+ * Two screens do the same three things — the enrolment prompt that appears
+ * after sign-in and the passkeys tab on the profile — and the enrolment
+ * ceremony in particular is three ordered steps (challenge, browser, store)
+ * where getting the order or the field names wrong fails at the authenticator
+ * rather than at a lint. Two inline copies of that would drift the first time
+ * one of them was fixed, so there is one, and both screens call it.
+ *
+ * Errors arrive as a plain `Error` carrying the server's message, with
+ * CustomFetch's automatic red toast suppressed: the caller decides what a
+ * failure looks like, and a cancelled ceremony (see `isPasskeyCancellation`)
+ * is not a failure at all.
+ */
+import CustomFetch from '../Fetch';
+import { resolveAuthEndpoints, resolvePasskeyDestroyUrl } from './authEndpoints';
+import { createPasskeyCredential } from './webauthn';
+import { countPasskeys, defaultPasskeyName } from './passkeyPrompt';
+
+/**
+ * CustomFetch as a plain promise, with its default error handling off.
+ *
+ * The same helper Login.jsx keeps for the sign-in ceremony, for the same
+ * reason — see the note there.
+ */
+const request = (url, method, body) =>
+    new Promise((resolve, reject) => {
+        CustomFetch(url, method, body, resolve, (message) =>
+            reject(new Error(message || 'Request failed.'))
+        );
+    });
+
+/**
+ * The passkeys this signed-in user holds.
+ *
+ * @param {object} [endpoints]  merged over DEFAULT_AUTH_ENDPOINTS.
+ * @returns {Promise<{passkeys: Array, count: number|null, payload: *}>}
+ */
+export const listPasskeys = async (endpoints) => {
+    const urls = resolveAuthEndpoints(endpoints);
+    const payload = await request(urls.passkeyIndex, 'GET');
+    const count = countPasskeys(payload);
+
+    return {
+        passkeys: Array.isArray(payload?.passkeys)
+            ? payload.passkeys
+            : Array.isArray(payload?.data)
+              ? payload.data
+              : Array.isArray(payload)
+                ? payload
+                : [],
+        count,
+        payload,
+    };
+};
+
+/**
+ * Enrol a passkey: challenge, ceremony, store.
+ *
+ * The browser's own sheet goes up in the middle step, and everything it can
+ * report — a dismissal, a timeout, an authenticator that refuses — comes back
+ * as a thrown DOMException the caller passes to `isPasskeyCancellation`.
+ *
+ * `name` becomes the credential's `alias`, which is the label the management
+ * list shows. Blank is allowed by the server; this sends the device name
+ * instead, because "This device" beside a date reads better than a date alone.
+ *
+ * @param {object} [endpoints]
+ * @param {{name?: string}} [options]
+ * @returns {Promise<*>} the server's response to the store step.
+ */
+export const enrolPasskey = async (endpoints, { name } = {}) => {
+    const urls = resolveAuthEndpoints(endpoints);
+
+    const options = await request(urls.passkeyRegisterOptions, 'POST', {});
+    const credential = await createPasskeyCredential(options);
+
+    const alias =
+        typeof name === 'string' && name.trim() !== ''
+            ? name.trim().slice(0, 60)
+            : defaultPasskeyName();
+
+    return request(urls.passkeyRegister, 'POST', {
+        ...credential,
+        alias,
+    });
+};
+
+/**
+ * Remove one credential.
+ *
+ * @param {object} [endpoints]
+ * @param {string} id  the credential id exactly as the server gave it.
+ */
+export const deletePasskey = (endpoints, id) => {
+    const urls = resolveAuthEndpoints(endpoints);
+
+    return request(resolvePasskeyDestroyUrl(urls.passkeyDestroy, id), 'DELETE');
+};
+
+export default enrolPasskey;

package/src/components/auth/passkeyPrompt.js

@@ -0,0 +1,408 @@
+/**
+ * WHETHER TO ASK THIS PERSON, ON THIS DEVICE, RIGHT NOW, TO ADD A PASSKEY.
+ *
+ * The prompt itself is four lines of dialog (see PasskeyEnrolPrompt.jsx). The
+ * part worth writing down — and the part that goes wrong — is the decision in
+ * front of it, because every way of getting it wrong is a nag:
+ *
+ *   - asked on a browser that cannot do WebAuthn: an offer the person cannot
+ *     accept, and no way to make it go away;
+ *   - asked on every page refresh instead of once per sign-in: the same dialog
+ *     four times in a working day;
+ *   - asked of somebody who ALREADY has a passkey, or who has just signed in
+ *     WITH one: the feature advertising itself to the people using it;
+ *   - asked again after "Don't ask again", because the record was written to a
+ *     storage that threw and nobody caught it.
+ *
+ * So the decision lives here, as one pure function over plain values, with the
+ * storage access beside it — and both are tested (tests/passkeyPrompt.test.mjs)
+ * rather than verified by signing in and out of an app.
+ *
+ * NOTHING IN THIS FILE IMPORTS ANYTHING. No React, no fetch, no stylesheet: it
+ * runs under `node --test` as-is, the same way authEndpoints.js and
+ * webauthn.js do.
+ */
+
+/**
+ * localStorage key prefix for the per-user dismissal record.
+ *
+ * Per USER, not per app: two accounts sharing a browser are two different
+ * answers to "do you want a passkey on this device", and the device is what
+ * localStorage already scopes to. The record is `{dismissedAt, never}`.
+ */
+export const PASSKEY_PROMPT_STORAGE_PREFIX = 'visns.passkeys.prompt.';
+
+/** How long "Not now" holds, in days, when the host names no other number. */
+export const DEFAULT_PASSKEY_SNOOZE_DAYS = 30;
+
+/** Milliseconds in a day, so the snooze arithmetic is readable. */
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * The dialog's words, all overridable through the `copy` key of the `passkeys`
+ * prop — the same arrangement Login and TwoFactorAuth use for theirs.
+ */
+export const DEFAULT_PASSKEY_PROMPT_COPY = {
+    title: 'Sign in faster next time',
+    body: 'Add a passkey and this device signs you in with your fingerprint, face or screen PIN — no password to type and nothing to remember. The passkey never leaves this device.',
+    add: 'Add passkey',
+    adding: 'Waiting for your device…',
+    later: 'Not now',
+    never: "Don't ask again",
+    success: 'Passkey added. You can use it to sign in from now on.',
+    failure: 'That passkey could not be added. Please try again.',
+};
+
+/**
+ * The `passkeys` prop, in one shape whatever the host passed.
+ *
+ * Three spellings, because the prop grew and the two older ones are in the
+ * wild:
+ *
+ *   undefined / false  the feature is off. Nothing renders — no button on the
+ *                      login screen, no tab on the profile, no prompt. An app
+ *                      that never passed the prop is unchanged.
+ *   true               what it has always meant (the login button), PLUS the
+ *                      enrolment prompt and the management tab.
+ *   {…}                the same as `true`, with the details named. Passing an
+ *                      object is itself the opt-in, so `enabled` only has to
+ *                      be written when it is `false` — which is how a host
+ *                      keeps one config object and switches the feature with
+ *                      one flag inside it.
+ *
+ * @param {boolean|object} [passkeys]
+ * @returns {{enabled: boolean, promptOnLogin: boolean, snoozeDays: number, copy: object}}
+ */
+export const resolvePasskeyOptions = (passkeys) => {
+    const off = {
+        enabled: false,
+        promptOnLogin: false,
+        snoozeDays: DEFAULT_PASSKEY_SNOOZE_DAYS,
+        copy: DEFAULT_PASSKEY_PROMPT_COPY,
+    };
+
+    if (!passkeys) {
+        return off;
+    }
+
+    if (passkeys === true || typeof passkeys !== 'object') {
+        return {
+            enabled: true,
+            promptOnLogin: true,
+            snoozeDays: DEFAULT_PASSKEY_SNOOZE_DAYS,
+            copy: DEFAULT_PASSKEY_PROMPT_COPY,
+        };
+    }
+
+    const enabled = passkeys.enabled !== false;
+    // Only the prompt is opt-OUT-able on its own: an app can offer passkeys on
+    // the login screen and in the profile without interrupting anybody.
+    const promptOnLogin = enabled && passkeys.promptOnLogin !== false;
+
+    const snoozeDays =
+        typeof passkeys.snoozeDays === 'number' &&
+        Number.isFinite(passkeys.snoozeDays) &&
+        passkeys.snoozeDays >= 0
+            ? passkeys.snoozeDays
+            : DEFAULT_PASSKEY_SNOOZE_DAYS;
+
+    return {
+        enabled,
+        promptOnLogin,
+        snoozeDays,
+        copy: { ...DEFAULT_PASSKEY_PROMPT_COPY, ...(passkeys.copy || {}) },
+    };
+};
+
+/** The localStorage key holding one user's answer. */
+export const passkeyPromptStorageKey = (userId) =>
+    `${PASSKEY_PROMPT_STORAGE_PREFIX}${userId}`;
+
+/**
+ * The storage to use: whatever was handed in, else `window.localStorage`.
+ *
+ * MERELY REACHING FOR `window.localStorage` CAN THROW — Safari with cookies
+ * blocked, a sandboxed iframe, a browser in a mode that disables site data —
+ * so even this is inside the try/catch, not only the get and set below.
+ *
+ * @param {Storage} [storage]  An explicit store, which is what the tests pass.
+ * @returns {Storage|null}
+ */
+const resolveStorage = (storage) => {
+    if (storage) {
+        return storage;
+    }
+
+    try {
+        if (typeof window === 'undefined') {
+            return null;
+        }
+
+        return window.localStorage || null;
+    } catch (error) {
+        return null;
+    }
+};
+
+/**
+ * This user's dismissal record, or null.
+ *
+ * Null means "nothing is on file" AND "the file could not be read" — which are
+ * the same thing to the caller: with no record the prompt is allowed, and a
+ * browser that cannot remember a dismissal cannot be nagged by one either,
+ * because the prompt is shown at most once per sign-in regardless.
+ *
+ * @param {string|number} userId
+ * @param {Storage} [storage]
+ * @returns {{dismissedAt: number, never: boolean}|null}
+ */
+export const readPasskeyPromptRecord = (userId, storage) => {
+    const store = resolveStorage(storage);
+
+    if (!store || userId === null || userId === undefined || userId === '') {
+        return null;
+    }
+
+    try {
+        const raw = store.getItem(passkeyPromptStorageKey(userId));
+
+        if (!raw) {
+            return null;
+        }
+
+        const parsed = JSON.parse(raw);
+
+        if (!parsed || typeof parsed !== 'object') {
+            return null;
+        }
+
+        return {
+            dismissedAt:
+                typeof parsed.dismissedAt === 'number' ? parsed.dismissedAt : 0,
+            never: parsed.never === true,
+        };
+    } catch (error) {
+        // Unparseable, unreadable, or a key some other version of this library
+        // wrote in another shape. Treated as absent rather than repaired.
+        return null;
+    }
+};
+
+/**
+ * Write this user's dismissal record. Silent on failure, by design: a storage
+ * that refuses the write must not take down the dialog that asked for it.
+ *
+ * @returns {boolean} whether it was stored.
+ */
+export const writePasskeyPromptRecord = (userId, record, storage) => {
+    const store = resolveStorage(storage);
+
+    if (!store || userId === null || userId === undefined || userId === '') {
+        return false;
+    }
+
+    try {
+        store.setItem(
+            passkeyPromptStorageKey(userId),
+            JSON.stringify({
+                dismissedAt:
+                    typeof record?.dismissedAt === 'number'
+                        ? record.dismissedAt
+                        : Date.now(),
+                never: record?.never === true,
+            })
+        );
+
+        return true;
+    } catch (error) {
+        return false;
+    }
+};
+
+/** "Not now" — hold the prompt back for `snoozeDays`. */
+export const snoozePasskeyPrompt = (userId, { now = Date.now(), storage } = {}) =>
+    writePasskeyPromptRecord(userId, { dismissedAt: now, never: false }, storage);
+
+/** "Don't ask again" — on this device, for this user, permanently. */
+export const neverAskPasskeyPrompt = (userId, { now = Date.now(), storage } = {}) =>
+    writePasskeyPromptRecord(userId, { dismissedAt: now, never: true }, storage);
+
+/**
+ * Does a stored record still hold the prompt back?
+ *
+ * `never` always does. A snooze does until `snoozeDays` have passed, counted
+ * from when it was taken. `snoozeDays: 0` means the snooze lasts until the
+ * next sign-in and no longer, which is a legitimate thing for a host to want
+ * and falls out of the arithmetic rather than needing a case of its own.
+ *
+ * A record with a `dismissedAt` in the future — a clock that was wrong, or has
+ * since been corrected — still counts as a dismissal for its window; nothing
+ * here tries to be cleverer than the device's own clock.
+ *
+ * @param {{dismissedAt: number, never: boolean}|null} record
+ * @param {{now?: number, snoozeDays?: number}} [options]
+ * @returns {boolean}
+ */
+export const isPasskeyPromptBlocked = (
+    record,
+    { now = Date.now(), snoozeDays = DEFAULT_PASSKEY_SNOOZE_DAYS } = {}
+) => {
+    if (!record) {
+        return false;
+    }
+
+    if (record.never === true) {
+        return true;
+    }
+
+    if (typeof record.dismissedAt !== 'number' || record.dismissedAt <= 0) {
+        return false;
+    }
+
+    return now < record.dismissedAt + snoozeDays * DAY_MS;
+};
+
+/**
+ * How many passkeys an `index` response says this user holds.
+ *
+ * The Laravel controller answers `{error, enabled, passkeys: [...]}`, but this
+ * reads the two other shapes a REST list arrives in as well — a bare array,
+ * and `{data: [...]}` — because the endpoint is overridable and the app on the
+ * other end of an overridden one is not this library's.
+ *
+ * ANYTHING UNRECOGNISABLE IS `null`, NOT `0`. "I could not tell" and "this
+ * person has none" lead to opposite decisions, and the gate below treats only
+ * a confident zero as a reason to prompt.
+ *
+ * @param {*} payload
+ * @returns {number|null}
+ */
+export const countPasskeys = (payload) => {
+    if (Array.isArray(payload)) {
+        return payload.length;
+    }
+
+    if (!payload || typeof payload !== 'object') {
+        return null;
+    }
+
+    const list = [payload.passkeys, payload.credentials, payload.data].find(
+        (candidate) => Array.isArray(candidate)
+    );
+
+    return list ? list.length : null;
+};
+
+/**
+ * THE DECISION. Every gate, in one place, over plain values.
+ *
+ * All of these must hold:
+ *
+ *   1. the host turned passkeys on, and left the prompt on;
+ *   2. the browser can do WebAuthn (`isPasskeySupported()`, passed in as
+ *      `supported` so this stays pure);
+ *   3. the person signed in during THIS page's life — not refreshed a page
+ *      that already had a session (see GenericAuth's `signInEvent`);
+ *   4. they did not sign in with a passkey, which would make the offer absurd;
+ *   5. we know who they are, because the dismissal is recorded against their
+ *      id and a prompt nobody can dismiss is a prompt that returns forever;
+ *   6. they hold no passkeys yet, KNOWN to be zero — an index request that
+ *      404ed, failed or answered something unreadable means no prompt;
+ *   7. nothing on this device says they already said no.
+ *
+ * @param {object}  input
+ * @param {object}  input.options         from `resolvePasskeyOptions`
+ * @param {boolean} input.supported       `isPasskeySupported()`
+ * @param {boolean} input.justSignedIn    a sign-in happened in this session
+ * @param {string}  [input.signInMethod]  'password' | 'passkey' | anything
+ * @param {string|number} [input.userId]
+ * @param {number|null} [input.credentialCount]  null when unknown
+ * @param {object|null} [input.record]    from `readPasskeyPromptRecord`
+ * @param {number} [input.now]
+ * @returns {boolean}
+ */
+export const shouldPromptForPasskey = ({
+    options,
+    supported,
+    justSignedIn,
+    signInMethod,
+    userId,
+    credentialCount,
+    record,
+    now = Date.now(),
+} = {}) => {
+    const resolved = options || resolvePasskeyOptions(false);
+
+    if (!resolved.enabled || !resolved.promptOnLogin) {
+        return false;
+    }
+
+    if (!supported || justSignedIn !== true) {
+        return false;
+    }
+
+    if (signInMethod === 'passkey') {
+        return false;
+    }
+
+    if (userId === null || userId === undefined || userId === '') {
+        return false;
+    }
+
+    if (typeof credentialCount !== 'number' || credentialCount > 0) {
+        return false;
+    }
+
+    return !isPasskeyPromptBlocked(record, {
+        now,
+        snoozeDays: resolved.snoozeDays,
+    });
+};
+
+/**
+ * A name for the credential about to be created.
+ *
+ * It is what the person will see in a list six months from now, next to two
+ * others, and the honest answer is which device it is on. `userAgentData`
+ * gives a browser brand without parsing a user-agent string; where it is
+ * missing — Safari, Firefox — the generic phrase is better than a regex over
+ * `navigator.userAgent`, which is a well-known way to be confidently wrong.
+ *
+ * Capped at 60 characters, which is the Laravel side's `alias_max_length`
+ * default; a longer one would come back as a validation error.
+ *
+ * @param {object} [nav]  `navigator`, injected so this can be tested.
+ * @returns {string}
+ */
+export const defaultPasskeyName = (nav) => {
+    const source =
+        nav || (typeof navigator !== 'undefined' ? navigator : undefined);
+
+    const brands = source?.userAgentData?.brands;
+    const brand = Array.isArray(brands)
+        ? brands
+              .map((entry) => entry?.brand)
+              .find(
+                  (name) =>
+                      typeof name === 'string' &&
+                      name !== '' &&
+                      // The deliberately meaningless entry every Chromium
+                      // browser includes to catch code that trusts the list.
+                      !/not.*a.*brand/i.test(name)
+              )
+        : null;
+
+    const platform =
+        typeof source?.userAgentData?.platform === 'string' &&
+        source.userAgentData.platform !== ''
+            ? source.userAgentData.platform
+            : '';
+
+    const name = brand
+        ? `${brand}${platform ? ` on ${platform}` : ''}`
+        : 'This device';
+
+    return name.slice(0, 60);
+};
+
+export default shouldPromptForPasskey;

package/src/components/auth/profileLayout.js

@@ -0,0 +1,45 @@
+import { isSidebarShell } from '../utils/useShellLayout';
+
+/**
+ * Where the Profile screen's tabs go.
+ *
+ * Split out of the component for the same reason `shouldUnderlineTabs` was
+ * split out of GenericIndex: it is the one decision here that fails silently.
+ * Pick the strip on a page that is already wearing a rail and you get two
+ * rails; pick the rail on a top-bar app and every existing deployment's
+ * account screen quietly changes shape. Neither shows up in a render test,
+ * because Profile imports stylesheets and a signature pad and the test runner
+ * cannot mount it — but the rule can be pinned exactly, and is (see
+ * tests/shellLayout.test.mjs).
+ *
+ * THE DEFAULT IS THE POINT. A host does not have to pass anything:
+ *
+ *   - `layout="full"` — the header-bar shell — keeps the rail it has always
+ *     had. The page has no other navigation column, so the rail costs nothing
+ *     that was being used for something else.
+ *   - `layout="cms"` / `layout="simple"` — the sidebar shells — get the strip.
+ *     On those the app's own navigation is ALREADY a vertical rail down the
+ *     left edge, and a second vertical rail immediately beside it is two
+ *     columns of navigation to reach two tabs.
+ *
+ * The shell layout comes from `<html data-layout>` (GenericAuth writes it; see
+ * utils/useShellLayout.js), so neither consuming app has to be edited for this
+ * to land the right way up.
+ *
+ * `tabLayout`, when it is one of the two names, wins over all of that — the
+ * usual escape hatch for the page that knows better than the rule.
+ *
+ * @param {object}   options
+ * @param {string}   [options.tabLayout]    'rail' | 'underline', or nothing.
+ * @param {string}   [options.shellLayout]  'full' | 'cms' | 'simple'.
+ * @returns {'rail'|'underline'}
+ */
+export function resolveProfileTabLayout({ tabLayout, shellLayout } = {}) {
+    if (tabLayout === 'rail' || tabLayout === 'underline') {
+        return tabLayout;
+    }
+
+    return isSidebarShell(shellLayout) ? 'underline' : 'rail';
+}
+
+export default resolveProfileTabLayout;

package/src/components/controls/DataGridSearch.jsx

@@ -174,7 +174,11 @@ const DataGridSearch = ({
         return (
             <div className={buttonClassName}>
                 {form.export && form.export.url && (
-                    <button className={styles.btn} onClick={exportTrigger}>
+                    <button
+                        className={styles.btn}
+                        title="Download what this grid is showing as a file"
+                        onClick={exportTrigger}
+                    >
                         <ExternalLink
                             strokeWidth={2}
                             size={16}
@@ -184,7 +188,11 @@ const DataGridSearch = ({
                     </button>
                 )}
                 {form.sort && form.sort.title && (
-                    <button className={styles.btn} onClick={sortTrigger}>
+                    <button
+                        className={styles.btn}
+                        title="Choose the order the rows are listed in"
+                        onClick={sortTrigger}
+                    >
                         <ArrowUpDown
                             strokeWidth={2}
                             size={16}
@@ -196,6 +204,7 @@ const DataGridSearch = ({
                 {form.bulkUpload && form.bulkUpload.enabled && (
                     <button
                         className={styles.btn}
+                        title="Add many records at once from a spreadsheet"
                         onClick={(e) => {
                             e.preventDefault();
                             if (onBulkUploadClick) {
@@ -218,6 +227,10 @@ const DataGridSearch = ({
                 (form.url && form.create?.title !== '') ? (
                     <button
                         className={styles.btn}
+                        title={
+                            form.create?.tooltip ||
+                            'Create a new record and add it to this list'
+                        }
                         onClick={(e) => {
                             e.preventDefault();
 
@@ -259,6 +272,7 @@ const DataGridSearch = ({
                 ) : form.url && form.modal === false ? (
                     <button
                         className={styles.btn}
+                        title="Create a new record and add it to this list"
                         onClick={(e) => {
                             e.preventDefault();
 

package/src/components/controls/DataGridSortSheet.jsx

@@ -118,6 +118,7 @@ const DataGridSortSheet = ({
                                 <span className={styles.sortSheetDirections}>
                                     <button
                                         type="button"
+                                        title={`List the rows by ${option.label}, smallest or earliest first`}
                                         aria-label={`Sort by ${option.label}, ascending`}
                                         aria-pressed={active && sort === 'asc'}
                                         className={
@@ -131,6 +132,7 @@ const DataGridSortSheet = ({
                                     </button>
                                     <button
                                         type="button"
+                                        title={`List the rows by ${option.label}, largest or latest first`}
                                         aria-label={`Sort by ${option.label}, descending`}
                                         aria-pressed={active && sort === 'desc'}
                                         className={