@webority/ui-react 0.17.3 → 0.18.0

package/THIRD-PARTY-NOTICES.txt

@@ -0,0 +1,23 @@
+@webority/ui-react includes a port (src/lib/qrCode.js, bundled into dist) of the following third-party software.
+
+QR Code generator library
+https://www.nayuki.io/page/qr-code-generator-library
+https://github.com/nayuki/QR-Code-generator
+
+Copyright (c) Project Nayuki. (MIT License)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+- The above copyright notice and this permission notice shall be included in
+  all copies or substantial portions of the Software.
+- The Software is provided "as is", without warranty of any kind, express or
+  implied, including but not limited to the warranties of merchantability,
+  fitness for a particular purpose and noninfringement. In no event shall the
+  authors or copyright holders be liable for any claim, damages or other
+  liability, whether in an action of contract, tort or otherwise, arising from,
+  out of or in connection with the Software or the use or other dealings in the
+  Software.

package/dist/types/components/AppColumnMenu.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A "Columns" menu that hides and shows a table's columns: one checkbox per column marked
+ * `hideable`. Put it in the table toolbar's actions and feed it from `useTableView`, which also
+ * hands the same `hiddenColumns` to `AppDataTable`. Razor counterpart: `<app-column-menu for="…" view-key="…">`.
+ *
+ * @param {object} props
+ * @param {{ key: string, label: import('react').ReactNode, hideable?: boolean }[]} props.columns The table's columns.
+ * @param {string[]} [props.hiddenColumns] Keys of the columns currently hidden.
+ * @param {(key: string) => void} props.onToggle Called with a column's key when its box changes.
+ * @param {string} [props.label="Columns"] Accessible name and tooltip of the button, and the menu heading.
+ * @param {string} [props.className] Extra classes on the menu panel.
+ */
+export default function AppColumnMenu({ columns, hiddenColumns, onToggle, label, className, ...rest }: {
+    columns: {
+        key: string;
+        label: import('react').ReactNode;
+        hideable?: boolean;
+    }[];
+    hiddenColumns?: string[];
+    onToggle: (key: string) => void;
+    label?: string;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/types/components/AppDataTable.d.ts

@@ -29,8 +29,17 @@
  * @param {boolean} [props.striped=false] Alternate-row shading in place of divider lines.
  * @param {string|number} [props.maxHeight] Caps the table's height; the body scrolls inside it with
  *   the header pinned. Without it there is no scroll box for the header to stick to.
+ * @param {string[]} [props.hiddenColumns] Keys of `hideable` columns to leave out (from useTableView).
+ *   A column that is not hideable always shows.
+ * @param {boolean} [props.stackOnMobile=false] Below 576px, shows each row as a card: the first
+ *   column on top, then "label: value" lines from the column labels, actions at the bottom.
  * @param {boolean} [props.stickyFirstColumn=false] Pins the first column (and the select/expand
  *   column before it) while a wide table scrolls sideways.
+ * @param {(row: object) => string} [props.rowHref] Makes the whole row open this URL on click or Enter
+ *   (Ctrl/Cmd or middle click opens a new tab). Checkboxes, buttons, links and menus in the row keep
+ *   their own behaviour. Razor: `data-href` on the <tr>.
+ * @param {(row: object) => void} [props.onRowClick] Called when the row is clicked or Enter is pressed
+ *   on it, for in-page actions (open a drawer). Same nested-control rule as rowHref.
  * @param {(row: object) => 'success'|'warning'|'danger'|'info'|undefined} [props.rowStatus] A coloured
  *   bar on the row's leading edge, e.g. danger for an overdue invoice. Undefined draws none.
  * @param {boolean} [props.selectable=false] Render a leading checkbox column.
@@ -40,7 +49,7 @@
  * @param {(row: object) => import('react').ReactNode} [props.renderExpanded] When given, each row
  *   gets a leading expand toggle; the returned content renders in a full-width row beneath it.
  */
-export default function AppDataTable({ columns, rows, rowKey, sort, onSort, loading, skeletonRows, empty, emptyFiltered, sourceCount, rowActions, rowActionsLabel, pagination, ariaLabel, className, wrapperClassName, selectable, selectedIds, onToggleRow, onToggleAll, renderExpanded, density, striped, maxHeight, stickyFirstColumn, rowStatus, ...rest }: {
+export default function AppDataTable({ columns, rows, rowKey, sort, onSort, loading, skeletonRows, empty, emptyFiltered, sourceCount, rowActions, rowActionsLabel, pagination, ariaLabel, className, wrapperClassName, selectable, selectedIds, onToggleRow, onToggleAll, renderExpanded, density, striped, maxHeight, stickyFirstColumn, stackOnMobile, hiddenColumns, rowStatus, rowHref, onRowClick, ...rest }: {
     columns: object[];
     rows: object[];
     rowKey?: (row: object, index: number) => string | number;
@@ -63,7 +72,11 @@ export default function AppDataTable({ columns, rows, rowKey, sort, onSort, load
     density?: 'comfortable' | 'cozy' | 'compact';
     striped?: boolean;
     maxHeight?: string | number;
+    hiddenColumns?: string[];
+    stackOnMobile?: boolean;
     stickyFirstColumn?: boolean;
+    rowHref?: (row: object) => string;
+    onRowClick?: (row: object) => void;
     rowStatus?: (row: object) => 'success' | 'warning' | 'danger' | 'info' | undefined;
     selectable?: boolean;
     selectedIds?: Set<string | number>;

package/dist/types/components/AppErrorSummary.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The list of a form's errors after a failed submit, each a link that moves focus to its field.
+ *
+ * Renders nothing while `errors` is empty. When errors appear it takes the focus itself, so a
+ * screen reader announces the title and the count, and a keyboard user starts from the list
+ * rather than from the Save button.
+ *
+ * @param {object} props
+ * @param {{ field: string, message: string }[]} [props.errors] `field` is the input's id or name.
+ * @param {import('react').ReactNode} [props.title] Heading. Defaults to "Fix N field(s) to continue".
+ * @param {boolean} [props.autoFocus=true] Take focus when errors appear. Turn off only where the
+ *   summary is shown for reference, such as documentation, never on a form.
+ * @param {string} [props.id]
+ * @param {string} [props.className]
+ */
+export default function AppErrorSummary({ errors, title, autoFocus, id, className, ...rest }: {
+    errors?: {
+        field: string;
+        message: string;
+    }[];
+    title?: import('react').ReactNode;
+    autoFocus?: boolean;
+    id?: string;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/types/components/AppFormSection.d.ts

@@ -4,16 +4,26 @@
  * Wraps a set of related fields with a section heading and intro text. Useful for
  * breaking large forms into digestible chunks. The body receives the fields; the
  * heading is outside so it stacks above the first field without wrapping it.
+ * Consecutive sections are set apart by space and a light rule.
  *
  * @param {object} props
  * @param {import('react').ReactNode} props.children The form fields.
  * @param {import('react').ReactNode} [props.title] Section heading (h3).
  * @param {import('react').ReactNode} [props.description] Intro text below the title (optional).
+ * @param {'stacked'|'side'} [props.layout='stacked'] `side` puts the title and description in a
+ *   column beside the fields from lg up; below that it stacks.
+ * @param {'top'|'start'} [props.labels='top'] `start` puts each field's label beside its control
+ *   (one field per row) from md up; below that labels sit on top.
+ * @param {'comfortable'|'compact'} [props.density='comfortable'] `compact` uses 36px controls and
+ *   tighter gaps, for admin screens and dialogs.
  * @param {string} [props.className]
  */
-export default function AppFormSection({ children, title, description, className, ...rest }: {
+export default function AppFormSection({ children, title, description, layout, labels, density, className, ...rest }: {
     children: import('react').ReactNode;
     title?: import('react').ReactNode;
     description?: import('react').ReactNode;
+    layout?: 'stacked' | 'side';
+    labels?: 'top' | 'start';
+    density?: 'comfortable' | 'compact';
     className?: string;
 }): import("react").JSX.Element;

package/dist/types/components/AppQrCode.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A scannable QR code, drawn as inline SVG. The React counterpart of `<app-qr-code>`.
+ *
+ * Drawn on a whole-module grid as ONE path, then scaled by a whole number of pixels per module. A
+ * fractional module size (a 200px box over 41 modules) lets the browser round each square
+ * differently, which leaves uneven modules and hairline seams between neighbours, and scanners
+ * refuse the result. `size` is therefore the largest the code may be, not its exact width.
+ *
+ * Black on white is a scan-reliability requirement, not a styling choice, so it ignores the theme
+ * and dark mode. Byte mode (UTF-8), medium error correction or higher, versions 1 to 40; text too
+ * long for a version 40 symbol throws.
+ *
+ * @param {object} props
+ * @param {string} props.value The text to encode, such as a URL, an otpauth:// URI or a signed token.
+ *   Nothing renders while it is empty.
+ * @param {number} [props.size=240] Largest width and height in px. The code renders at the biggest
+ *   whole number of pixels per module that fits.
+ * @param {string} [props.title='QR code'] Accessible name. Say what scanning it does.
+ * @param {string} [props.className]
+ * @param {import('react').CSSProperties} [props.style]
+ */
+export default function AppQrCode({ value, size, title, className, style, ...rest }: {
+    value: string;
+    size?: number;
+    title?: string;
+    className?: string;
+    style?: import('react').CSSProperties;
+}): import("react").JSX.Element;

package/dist/types/components/AppRadioGroup.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A labelled set of radio buttons, laid out like every other field: the group's label sits
+ * where a text field's label does (above, or beside it under `AppFormSection labels="start"`),
+ * with the hint or error below.
+ *
+ * The group is a `role="radiogroup"` named by its label rather than a fieldset/legend: a
+ * legend renders at heading size and cannot take part in the field grid, so the label would
+ * sit apart from every other field on the form.
+ *
+ * @param {object} props
+ * @param {import('react').ReactNode} props.label Visible group label; also the group's accessible name.
+ * @param {{ value: string, label: import('react').ReactNode, disabled?: boolean }[]} props.options
+ * @param {string} [props.name] Shared name of the radios. Defaults to a generated one.
+ * @param {string} [props.value] Selected value (controlled).
+ * @param {string} [props.defaultValue] Initially selected value (uncontrolled).
+ * @param {(value: string) => void} [props.onChange]
+ * @param {boolean} [props.inline=false] Options in a row (wrapping) instead of a column.
+ * @param {boolean} [props.required=false]
+ * @param {boolean} [props.disabled=false] Disables every option.
+ * @param {string} [props.error] Error message below the group. Replaces the hint.
+ * @param {string} [props.hint] Helper text below the group.
+ * @param {import('react').ReactNode} [props.help] Content for the label info-tip.
+ * @param {string} [props.helpLabel="More information"] aria-label for the info-tip button.
+ * @param {string} [props.id]
+ * @param {string} [props.className] Class on the group (the control).
+ * @param {import('react').CSSProperties} [props.style] Inline style; lands on the group with `className`.
+ * @param {string} [props.fieldClassName] Class on the `.field` wrapper.
+ */
+export default function AppRadioGroup({ label, options, name, value, defaultValue, onChange, inline, required, disabled, error, hint, help, helpLabel, id, className, fieldClassName, style, ...rest }: {
+    label: import('react').ReactNode;
+    options: {
+        value: string;
+        label: import('react').ReactNode;
+        disabled?: boolean;
+    }[];
+    name?: string;
+    value?: string;
+    defaultValue?: string;
+    onChange?: (value: string) => void;
+    inline?: boolean;
+    required?: boolean;
+    disabled?: boolean;
+    error?: string;
+    hint?: string;
+    help?: import('react').ReactNode;
+    helpLabel?: string;
+    id?: string;
+    className?: string;
+    style?: import('react').CSSProperties;
+    fieldClassName?: string;
+}): import("react").JSX.Element;

package/dist/types/index.d.ts

@@ -15,6 +15,7 @@ export { default as AppChip } from "./components/AppChip.jsx";
 export { default as AppChoiceCard } from "./components/AppChoiceCard.jsx";
 export { default as AppChoiceChip } from "./components/AppChoiceChip.jsx";
 export { default as AppColorField } from "./components/AppColorField.jsx";
+export { default as AppColumnMenu } from "./components/AppColumnMenu.jsx";
 export { default as AppCommandPalette } from "./components/AppCommandPalette.jsx";
 export { default as AppCompareTable } from "./components/AppCompareTable.jsx";
 export { default as AppConfirmDialog } from "./components/AppConfirmDialog.jsx";
@@ -27,6 +28,7 @@ export { default as AppDateRangePicker } from "./components/AppDateRangePicker.j
 export { default as AppDescriptions } from "./components/AppDescriptions.jsx";
 export { default as AppDropdown } from "./components/AppDropdown.jsx";
 export { default as AppEmptyState } from "./components/AppEmptyState.jsx";
+export { default as AppErrorSummary } from "./components/AppErrorSummary.jsx";
 export { default as AppFileAttachment } from "./components/AppFileAttachment.jsx";
 export { default as AppFilePicker } from "./components/AppFilePicker.jsx";
 export { default as AppFloatingDock } from "./components/AppFloatingDock.jsx";
@@ -51,7 +53,9 @@ export { default as AppPhoneNumberInput } from "./components/AppPhoneNumberInput
 export { default as AppPopover } from "./components/AppPopover.jsx";
 export { default as AppPricingCard } from "./components/AppPricingCard.jsx";
 export { default as AppProgress } from "./components/AppProgress.jsx";
+export { default as AppQrCode } from "./components/AppQrCode.jsx";
 export { default as AppRadio } from "./components/AppRadio.jsx";
+export { default as AppRadioGroup } from "./components/AppRadioGroup.jsx";
 export { default as AppRepeater } from "./components/AppRepeater.jsx";
 export { default as AppRequiredMark } from "./components/AppRequiredMark.jsx";
 export { default as AppResourceCard } from "./components/AppResourceCard.jsx";
@@ -87,3 +91,4 @@ export { MODAL_ICONS } from "./components/ModalIcons.jsx";
 export { dismissAll, errorToast, toast } from "./components/toast.js";
 export { useCommandPaletteShortcut } from "./lib/useCommandPaletteShortcut.js";
 export { usePagination } from "./lib/usePagination.js";
+export { useTableView } from "./lib/useTableView.js";

package/dist/types/lib/focusField.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Moves focus to a form field named by its id or its `name`, scrolling it to the middle of the
+ * view so its label shows too. A custom-element field (a select, a date picker) carries the id or
+ * name on its host, so the first focusable element inside the match takes the focus. A hidden
+ * form mirror shares the name and is skipped.
+ *
+ * @param {string} field The field's id or name.
+ * @returns {boolean} Whether a field took the focus.
+ * @internal shared by AppErrorSummary; Razor's webority-ui.js carries the same lookup.
+ */
+export default function focusField(field: string): boolean;

package/dist/types/lib/qrCode.d.ts

@@ -0,0 +1,72 @@
+/*! @license
+ * QR Code encoder, ported from the QR Code generator library by Project Nayuki.
+ * https://www.nayuki.io/page/qr-code-generator-library
+ *
+ * Copyright (c) Project Nayuki. (MIT License)
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ * - The above copyright notice and this permission notice shall be included in
+ *   all copies or substantial portions of the Software.
+ * - The Software is provided "as is", without warranty of any kind, express or
+ *   implied, including but not limited to the warranties of merchantability,
+ *   fitness for a particular purpose and noninfringement. In no event shall the
+ *   authors or copyright holders be liable for any claim, damages or other
+ *   liability, whether in an action of contract, tort or otherwise, arising from,
+ *   out of or in connection with the Software or the use or other dealings in the
+ *   Software.
+ */
+export type QrMatrix = {
+    /**
+     * Modules per side, 21 to 177.
+     */
+    size: number;
+    /**
+     * 1 to 40.
+     */
+    version: number;
+    /**
+     * The level actually used, which can be above the one asked for.
+     */
+    ecc: 'L' | 'M' | 'Q' | 'H';
+    /**
+     * 0 to 7.
+     */
+    mask: number;
+    isDark: (row: number, col: number) => boolean;
+};
+/**
+ * An encoded QR symbol: a square grid of dark and light modules, without the quiet zone.
+ * @typedef {object} QrMatrix
+ * @property {number} size Modules per side, 21 to 177.
+ * @property {number} version 1 to 40.
+ * @property {'L'|'M'|'Q'|'H'} ecc The level actually used, which can be above the one asked for.
+ * @property {number} mask 0 to 7.
+ * @property {(row: number, col: number) => boolean} isDark
+ */
+/**
+ * Encodes text as a QR symbol in byte mode (UTF-8), choosing the smallest version that fits.
+ * The error correction level is a minimum: it is raised while the data still fits the same version.
+ *
+ * @param {string} text
+ * @param {'L'|'M'|'Q'|'H'} [ecc='M']
+ * @param {{ mask?: number, boostEcc?: boolean }} [options] mask -1 chooses the best of the eight.
+ * @returns {QrMatrix}
+ */
+export declare function encodeQr(text: string, ecc?: 'L' | 'M' | 'Q' | 'H', { mask, boostEcc }?: {
+    mask?: number;
+    boostEcc?: boolean;
+}): QrMatrix;
+/**
+ * The dark modules as ONE SVG path on a whole-module grid: one rectangle per horizontal run,
+ * offset by the quiet zone. The viewBox is `size + 2 * quietZone` modules square.
+ *
+ * @param {QrMatrix} matrix
+ * @param {number} [quietZone=4]
+ * @returns {string}
+ */
+export declare function qrSvgPath(matrix: QrMatrix, quietZone?: number): string;

package/dist/types/lib/useTableView.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Hidden columns and sort for one table, remembered per browser.
+ *
+ * @param {string} viewKey Names the view, e.g. "invoices". Two tables sharing a key share a view.
+ * @param {{ sort?: { key: string, dir: "asc"|"desc" } }} [options] The sort to start from.
+ * @returns {{ hiddenColumns: string[], toggleColumn: (key: string) => void,
+ *   sort: { key: string, dir: "asc"|"desc" }|undefined, setSort: (next: object|((prev: object) => object)) => void }}
+ */
+export declare function useTableView(viewKey: string, { sort: initialSort }?: {
+    sort?: {
+        key: string;
+        dir: "asc" | "desc";
+    };
+}): {
+    hiddenColumns: string[];
+    toggleColumn: (key: string) => void;
+    sort: {
+        key: string;
+        dir: "asc" | "desc";
+    } | undefined;
+    setSort: (next: object | ((prev: object) => object)) => void;
+};