@webority/ui-react 0.88.0 → 0.89.0

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

@@ -8,15 +8,28 @@ import "@webority/ui-elements/elements/overflow";
  *
  * @param {object} props
  * @param {import('react').ReactNode} props.children The chips.
- * @param {"wrap"|"menu"} [props.overflow="wrap"] `wrap` lets the chips wrap; `menu` moves the extras into a More menu.
- * @param {string} [props.moreLabel="More"] The More button's text when `overflow="menu"`.
- * @param {string} [props.label] Accessible name for the group.
+ * @param {"wrap"|"menu"} [props.overflow]
+ * @param {string} [props.moreLabel]
+ * @param {string} [props.label]
  * @param {string} [props.className]
  */
 export default function AppChipGroup(props: {
     children: import('react').ReactNode;
+    /**
+     * `wrap` lets the chips wrap; `menu` moves the extras into a More menu.
+     * @default "wrap"
+     */
     overflow?: "wrap" | "menu";
+    /**
+     * The More button text when overflow is menu.
+     * @default "More"
+     */
     moreLabel?: string;
+    /** Accessible name for the group. */
     label?: string;
+    /**
+     * Extra class names added to the group.
+     * @default ""
+     */
     className?: string;
 }): import("react").JSX.Element;

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

@@ -3,49 +3,90 @@
  *
  * @param {object} props
  * @param {string} props.name
- * @param {boolean} [props.multiple=false] Render as a checkbox (multi-select) rather than a radio.
+ * @param {boolean} [props.multiple]
  * @param {string} props.value
  * @param {boolean} props.checked
  * @param {(e: import('react').ChangeEvent<HTMLInputElement>) => void} props.onChange
- * @param {string} [props.icon] Icon name. Renders linear, and switches to the solid (bold) style
- *   while the card is checked so the selected card reads at a glance.
+ * @param {string} [props.icon]
  * @param {import('react').ReactNode} [props.iconNode]
- * @param {number} [props.iconSize] Icon glyph size in px. Defaults to the card size: 16 (sm), 18 (md), 22 (lg).
- * @param {string} [props.image] Image URL — renders an image-forward card (overrides `icon`).
+ * @param {number} [props.iconSize]
+ * @param {string} [props.image]
  * @param {string} [props.imageAlt]
  * @param {import('react').ReactNode} [props.children] Custom body, overriding title/description.
  * @param {import('react').ReactNode} props.title
  * @param {import('react').ReactNode} [props.description]
- * @param {string} [props.checkIcon="check"]
- * @param {number} [props.checkSize=18]
- * @param {boolean} [props.hideCheck=false] Render no selected tick. Selection then reads from the
- *   card's border and fill alone, and the card sheds the top/bottom room the tick needed.
- * @param {boolean} [props.disabled=false] The card cannot change: no pointer, no hover, announced as disabled. A disabled parent fieldset does the same.
- * @param {'sm'|'md'|'lg'} [props.size='md'] Card size: padding, gap, icon disc, type and the
- *   tick offset step together.
- * @param {'inline'|'stacked'} [props.layout='inline'] `inline` puts the icon beside the text;
- *   `stacked` puts the icon on its own line with the title and description below it.
+ * @param {string} [props.checkIcon]
+ * @param {number} [props.checkSize]
+ * @param {boolean} [props.hideCheck]
+ * @param {boolean} [props.disabled]
+ * @param {'sm'|'md'|'lg'} [props.size]
+ * @param {'inline'|'stacked'} [props.layout]
  * @param {string} [props.className]
  */
 export default function AppChoiceCard(props: {
+    /** Shared form name. Cards with the same name form one group. */
     name: string;
+    /**
+     * Render as a checkbox (multi-select) rather than a radio.
+     * @default false
+     */
     multiple?: boolean;
+    /** The value this card submits when selected. */
     value: string;
+    /** Whether the card is selected. */
     checked: boolean;
     onChange: (e: import('react').ChangeEvent<HTMLInputElement>) => void;
+    /** Icon name. Renders linear, and switches to the solid (bold) style while the card is checked so the selected card reads at a glance. */
     icon?: string;
+    /** Custom icon content, used in place of icon. */
     iconNode?: import('react').ReactNode;
+    /** Icon glyph size in px. Defaults to the card size: 16 (sm), 18 (md), 22 (lg). */
     iconSize?: number;
+    /** Image URL. Renders an image-forward card (overrides icon). */
     image?: string;
+    /**
+     * Alternative text for the image.
+     * @default ""
+     */
     imageAlt?: string;
     children?: import('react').ReactNode;
+    /** The card title. */
     title: import('react').ReactNode;
+    /** Secondary text under the title. */
     description?: import('react').ReactNode;
+    /**
+     * Icon name for the selected tick.
+     * @default "check"
+     */
     checkIcon?: string;
+    /**
+     * Tick icon size in px.
+     * @default 18
+     */
     checkSize?: number;
+    /**
+     * Render no selected tick. Selection then reads from the card's border and fill alone, and the card sheds the top and bottom room the tick needed.
+     * @default false
+     */
     hideCheck?: boolean;
+    /**
+     * The card cannot change: no pointer, no hover, announced as disabled. A disabled parent fieldset does the same.
+     * @default false
+     */
     disabled?: boolean;
+    /**
+     * Card size: padding, gap, icon disc, type and the tick offset step together.
+     * @default "md"
+     */
     size?: 'sm' | 'md' | 'lg';
+    /**
+     * `inline` puts the icon beside the text; `stacked` puts the icon on its own line with the title and description below it.
+     * @default "inline"
+     */
     layout?: 'inline' | 'stacked';
+    /**
+     * Extra class names added to the card.
+     * @default ""
+     */
     className?: string;
 }): import("react").JSX.Element;

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

@@ -2,29 +2,49 @@
  * Selectable chip for multi/single-select pills (.choice-chip).
  *
  * @param {object} props
- * @param {boolean} [props.multiple=true] Checkbox (multi-select) when true, radio when false.
- * @param {import('react').ReactNode} [props.label] Chip text (or use `children`).
+ * @param {boolean} [props.multiple]
+ * @param {import('react').ReactNode} [props.label]
  * @param {string} [props.name]
  * @param {string} [props.value]
  * @param {boolean} props.checked
  * @param {(e: import('react').ChangeEvent<HTMLInputElement>) => void} props.onChange
  * @param {import('react').ReactNode} props.children
- * @param {import('react').ReactNode} [props.count] A matching-row count, e.g. "Active 12".
- *   Shown as a small badge that inverts when the chip is selected.
- * @param {'sm'|'md'|'lg'} [props.size='md'] Pill size — padding, gap and font step together.
- * @param {boolean} [props.disabled=false] The chip dims and cannot be picked.
+ * @param {import('react').ReactNode} [props.count]
+ * @param {'sm'|'md'|'lg'} [props.size]
+ * @param {boolean} [props.disabled]
  * @param {string} [props.className]
  */
 export default function AppChoiceChip(props: {
+    /**
+     * Checkbox (multi-select) when true, radio when false.
+     * @default true
+     */
     multiple?: boolean;
+    /** Chip text. Children work in its place. */
     label?: import('react').ReactNode;
+    /** Shared form name. Chips with the same name form one group. */
     name?: string;
+    /** The value this chip submits when selected. */
     value?: string;
+    /** Whether the chip is selected. */
     checked: boolean;
     onChange: (e: import('react').ChangeEvent<HTMLInputElement>) => void;
     children: import('react').ReactNode;
+    /** A matching-row count, such as Active 12. Shown as a small badge that inverts when the chip is selected. */
     count?: import('react').ReactNode;
+    /**
+     * Pill size: padding, gap and font step together.
+     * @default "md"
+     */
     size?: 'sm' | 'md' | 'lg';
+    /**
+     * The chip dims and cannot be picked.
+     * @default false
+     */
     disabled?: boolean;
+    /**
+     * Extra class names added to the chip.
+     * @default ""
+     */
     className?: string;
 }): import("react").JSX.Element;

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

@@ -7,22 +7,42 @@ import "@webority/ui-elements/elements/code-block";
  * beyond 100,000 characters is shown uncoloured. Not an editor: it shows code, it does not edit it.
  *
  * @param {object} props
- * @param {string} props.code The source text. A single trailing newline is dropped.
- * @param {"text"|"json"|"js"|"cs"|"sql"|"bash"|"http"|"html"|"css"} [props.language="text"] What to colour; `text` shows it as written.
- * @param {boolean} [props.lineNumbers=false] Number the lines. The numbers are not copied or selected.
- * @param {boolean} [props.wrap=false] Wrap long lines instead of scrolling sideways.
- * @param {string} [props.label] The header title ("webhook.json") and the code region's accessible name. Without it the header names the language.
- * @param {string} [props.copyLabel="Copy"] The copy button's label.
- * @param {string} [props.copiedLabel="Copied"] The copy button's label for two seconds after a copy.
+ * @param {string} props.code
+ * @param {"text"|"json"|"js"|"cs"|"sql"|"bash"|"http"|"html"|"css"} [props.language]
+ * @param {boolean} [props.lineNumbers]
+ * @param {boolean} [props.wrap]
+ * @param {string} [props.label]
+ * @param {string} [props.copyLabel]
+ * @param {string} [props.copiedLabel]
  * @param {string} [props.className]
  */
 export default function AppCodeBlock(props: {
+    /** The source text. A single trailing newline is dropped. */
     code: string;
+    /**
+     * What to colour; `text` shows it as written.
+     * @default "text"
+     */
     language?: "text" | "json" | "js" | "cs" | "sql" | "bash" | "http" | "html" | "css";
+    /**
+     * Number the lines. The numbers are not copied or selected.
+     * @default false
+     */
     lineNumbers?: boolean;
+    /**
+     * Wrap long lines instead of scrolling sideways.
+     * @default false
+     */
     wrap?: boolean;
+    /** The header title, such as webhook.json, and the code region's accessible name. Without it the header names the language. */
     label?: string;
+    /** The copy button's label. It reads Copy when left out. */
     copyLabel?: string;
+    /** The copy button's label for two seconds after a copy. It reads Copied when left out. */
     copiedLabel?: string;
+    /**
+     * Extra class on the root.
+     * @default ""
+     */
     className?: string;
 }): import("react").JSX.Element;

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

@@ -10,31 +10,59 @@
  * once the value is complete rather than on every keystroke.
  *
  * @param {object} props
- * @param {string} props.value Hex colour, e.g. "#4F46E5".
+ * @param {string} [props.value]
  * @param {(hex: string) => void} props.onChange
  * @param {import('react').ReactNode} [props.label]
- * @param {boolean} [props.required=false]
+ * @param {boolean} [props.required]
  * @param {string} [props.error]
  * @param {string} [props.hint]
  * @param {string} [props.name]
  * @param {string} [props.id]
- * @param {boolean} [props.disabled=false]
- * @param {"sm"|"md"|"lg"} [props.size="md"] Control size — sm/lg opt out of the shared height,
- *   resizing both the swatch and the hex box together.
- * @param {string} [props.className] Applied to the hex text input (the control).
- * @param {string} [props.fieldClassName] Applied to the `.field` wrapper.
+ * @param {boolean} [props.disabled]
+ * @param {"sm"|"md"|"lg"} [props.size]
+ * @param {string} [props.className]
+ * @param {string} [props.fieldClassName]
  */
 export default function AppColorField(props: {
-    value: string;
+    /**
+     * Hex colour, for example #4F46E5.
+     * @default "#000000"
+     */
+    value?: string;
     onChange: (hex: string) => void;
+    /** The field label. */
     label?: import('react').ReactNode;
+    /**
+     * Marks the field as required.
+     * @default false
+     */
     required?: boolean;
+    /** Error message shown under the field. */
     error?: string;
+    /** Helper text shown under the field. */
     hint?: string;
+    /** Form field name on the text box, the control that posts. */
     name?: string;
+    /** Element id of the hex text box. Defaults to a generated id, not name. */
     id?: string;
+    /**
+     * The field cannot change.
+     * @default false
+     */
     disabled?: boolean;
+    /**
+     * Control size. sm and lg resize the swatch and the hex box together.
+     * @default "md"
+     */
     size?: "sm" | "md" | "lg";
+    /**
+     * Applied to the hex text input, the control.
+     * @default ""
+     */
     className?: string;
+    /**
+     * Applied to the field wrapper.
+     * @default ""
+     */
     fieldClassName?: string;
 }): import("react").JSX.Element;

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

@@ -4,20 +4,33 @@
  * 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, label: import('react').ReactNode, hideable?: boolean }[]} props.columns
+ * @param {string[]} [props.hiddenColumns]
  * @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.
+ * @param {string} [props.label]
+ * @param {string} [props.className]
  */
 export default function AppColumnMenu(props: {
+    /** The table's columns. */
     columns: {
         key: string;
         label: import('react').ReactNode;
         hideable?: boolean;
     }[];
+    /**
+     * Keys of the columns currently hidden.
+     * @default []
+     */
     hiddenColumns?: string[];
     onToggle: (key: string) => void;
+    /**
+     * Accessible name and tooltip of the button, and the menu heading.
+     * @default "Columns"
+     */
     label?: string;
+    /**
+     * Extra classes on the menu panel.
+     * @default ""
+     */
     className?: string;
 }): import("react").JSX.Element;

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

@@ -24,50 +24,50 @@ import "@webority/ui-elements/elements/command-palette";
  * @param {object} props
  * @param {boolean} props.open
  * @param {() => void} props.onClose Called on Escape, a backdrop click, and after a selection.
- * @param {string} [props.query=''] The search text (controlled).
+ * @param {string} [props.query]
  * @param {(value: string) => void} [props.onQueryChange] Called with the new text as the user types.
- * @param {string} [props.placeholder='Search…']
+ * @param {string} [props.placeholder]
  * @param {{ key: string, label: import('react').ReactNode, items: { key: string,
  *   label: import('react').ReactNode, description?: import('react').ReactNode,
  *   icon?: string | import('react').ReactNode, meta?: import('react').ReactNode,
  *   disabled?: boolean, ariaLabel?: string, shortcut?: string,
- *   page?: { key: string, label: string }, onSelect?: () => void }[] }[]} [props.groups=[]]
- *   Results, rendered in order under their group headings. Keys must be unique within their
- *   group; groups with no items are left out. `icon` is a library icon name or a node; `meta` is
- *   short trailing text or a node. A `disabled` item is listed but cannot be chosen: the arrow
- *   keys skip it. `ariaLabel` is the option's accessible name, by default a string `label`, so a
- *   screen reader reads the name whole rather than in the pieces the search emphasis splits it
- *   into; give it for a label passed as a node. The description and meta describe the option.
- *   `shortcut` is the key that runs the item elsewhere ("N", "Ctrl K"), drawn as a key chip at
- *   the end of the row; it is a hint, your page binds the key. `page` makes the item open a
- *   nested page ({ key, label }, the label shows in the breadcrumb) instead of calling `onSelect`.
- * @param {{ key: string, label: string }[]} [props.path=[]] The open nested pages, outermost first
- *   (controlled). Empty shows the first page.
+ *   page?: { key: string, label: string }, onSelect?: () => void }[] }[]} [props.groups]
+ * @param {{ key: string, label: string }[]} [props.path]
  * @param {(path: { key: string, label: string }[]) => void} [props.onPathChange] Called with the
  *   new path when the user opens a page, presses Back, picks a breadcrumb entry, or presses
  *   Backspace in an empty search. The search is cleared with it.
- * @param {string} [props.rootLabel='All'] Breadcrumb text for the first page.
- * @param {string} [props.backLabel='Back'] Accessible name of the Back button.
- * @param {string} [props.recentsKey] localStorage key to remember chosen items under; omit for no
- *   recents. Make it per user, for example from the user's public id.
- * @param {number} [props.recentsLimit=5] How many recent items to keep (at most 20).
- * @param {string} [props.recentsLabel='Recent'] Heading of the recent items.
- * @param {boolean} [props.loading=false] Shows the library spinner in the input.
- * @param {import('react').ReactNode} [props.emptyText='No results'] Shown when the query is
- *   not blank, nothing is loading, and no group has items.
- * @param {import('react').ReactNode} [props.footer] Content under the list, such as key hints.
- * @param {string} [props.ariaLabel='Search'] Accessible name of the dialog and its input.
- * @param {boolean} [props.highlight=true] Bold the query inside each string label,
- *   case-insensitively. A label given as a node renders as it is.
- * @param {string} [props.id] Seeds the result and heading ids; defaults to a generated id.
- * @param {string} [props.className] Extra classes on the dialog card.
+ * @param {string} [props.rootLabel]
+ * @param {string} [props.backLabel]
+ * @param {string} [props.recentsKey]
+ * @param {number} [props.recentsLimit]
+ * @param {string} [props.recentsLabel]
+ * @param {boolean} [props.loading]
+ * @param {import('react').ReactNode} [props.emptyText]
+ * @param {import('react').ReactNode} [props.footer]
+ * @param {string} [props.ariaLabel]
+ * @param {boolean} [props.highlight]
+ * @param {string} [props.id]
+ * @param {string} [props.className]
  */
 export default function AppCommandPalette(props: {
+    /** Shows the palette while true. */
     open: boolean;
     onClose: () => void;
+    /**
+     * The search text (controlled).
+     * @default ""
+     */
     query?: string;
     onQueryChange?: (value: string) => void;
+    /**
+     * The text the search field shows while it is empty.
+     * @default "Search…"
+     */
     placeholder?: string;
+    /**
+     * Results, rendered in order under their group headings; groups with no items are left out.
+     * @default []
+     */
     groups?: {
         key: string;
         label: import('react').ReactNode;
@@ -87,6 +87,10 @@ export default function AppCommandPalette(props: {
             onSelect?: () => void;
         }[];
     }[];
+    /**
+     * The open nested pages, outermost first (controlled); empty shows the first page.
+     * @default []
+     */
     path?: {
         key: string;
         label: string;
@@ -95,16 +99,55 @@ export default function AppCommandPalette(props: {
         key: string;
         label: string;
     }[]) => void;
+    /**
+     * Breadcrumb text for the first page.
+     * @default "All"
+     */
     rootLabel?: string;
+    /**
+     * Accessible name of the Back button.
+     * @default "Back"
+     */
     backLabel?: string;
+    /** localStorage key to remember chosen items under; omit for no recents. Make it per user, for example from the user's public id. */
     recentsKey?: string;
+    /**
+     * How many recent items to keep (at most 20).
+     * @default 5
+     */
     recentsLimit?: number;
+    /**
+     * Heading of the recent items.
+     * @default "Recent"
+     */
     recentsLabel?: string;
+    /**
+     * Shows the library spinner in the input.
+     * @default false
+     */
     loading?: boolean;
+    /**
+     * Shown when the query is not blank, nothing is loading, and no group has items.
+     * @default "No results"
+     */
     emptyText?: import('react').ReactNode;
+    /** Content under the list, such as key hints. */
     footer?: import('react').ReactNode;
+    /**
+     * Accessible name of the dialog and its input.
+     * @default "Search"
+     */
     ariaLabel?: string;
+    /**
+     * Bold the query inside each string label, case-insensitively. A label given as a node renders as it is.
+     * @default true
+     */
     highlight?: boolean;
+    /** Seeds the result and heading ids; defaults to a generated id. */
     id?: string;
+    /**
+     * Extra classes on the dialog card.
+     * @default ""
+     */
     className?: string;
 }): import("react").JSX.Element;

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

@@ -71,7 +71,7 @@ export type CommentThreadItem = {
  * @property {CommentThreadItem[]} [replies] Replies, oldest first. Replies to a reply are not nested.
  *
  * @param {object} props
- * @param {CommentThreadItem[]} [props.comments] Top-level comments, oldest first.
+ * @param {CommentThreadItem[]} [props.comments]
  * @param {(body: string) => unknown | Promise<unknown>} [props.onPost] A new comment.
  * @param {(parentId: string, body: string) => unknown | Promise<unknown>} [props.onReply]
  * @param {(commentId: string, body: string) => unknown | Promise<unknown>} [props.onEdit]
@@ -79,22 +79,26 @@ export type CommentThreadItem = {
  * @param {(commentId: string, emoji: string) => unknown | Promise<unknown>} [props.onReact] Toggle
  *   this person's reaction.
  * @param {{ value: string, label: string, description?: string, src?: string }[]} [props.people]
- *   The people the boxes offer after "@".
  * @param {(query: string) => Promise<{ value: string, label: string, description?: string, src?: string }[]>} [props.loadPeople]
  *   Look people up instead of `people`.
- * @param {string[]} [props.reactionChoices] The reactions the panel offers (default 👍 ❤️ 🎉 😄 👀 🙏).
- * @param {boolean} [props.readOnly=false] Show the thread without the box, actions or reacting.
- * @param {string} [props.label="Comments"] The list's accessible name.
- * @param {string} [props.id] The root's id. Generated when omitted.
- * @param {string} [props.className] Extra classes on the root.
+ * @param {string[]} [props.reactionChoices]
+ * @param {boolean} [props.readOnly]
+ * @param {string} [props.label]
+ * @param {string} [props.id]
+ * @param {string} [props.className]
  */
 export default function AppCommentThread(props: {
+    /**
+     * Top-level comments, oldest first.
+     * @default []
+     */
     comments?: CommentThreadItem[];
     onPost?: (body: string) => unknown | Promise<unknown>;
     onReply?: (parentId: string, body: string) => unknown | Promise<unknown>;
     onEdit?: (commentId: string, body: string) => unknown | Promise<unknown>;
     onDelete?: (commentId: string) => unknown | Promise<unknown>;
     onReact?: (commentId: string, emoji: string) => unknown | Promise<unknown>;
+    /** The people the boxes offer after @. */
     people?: {
         value: string;
         label: string;
@@ -107,9 +111,23 @@ export default function AppCommentThread(props: {
         description?: string;
         src?: string;
     }[]>;
+    /** The reactions the panel offers. Without it the panel offers a thumbs up, heart, party, smile, eyes and folded hands. */
     reactionChoices?: string[];
+    /**
+     * Show the thread without the box, actions or reacting.
+     * @default false
+     */
     readOnly?: boolean;
+    /**
+     * The list's accessible name.
+     * @default "Comments"
+     */
     label?: string;
+    /** The root's id. Generated when omitted. */
     id?: string;
+    /**
+     * Extra classes on the root.
+     * @default ""
+     */
     className?: string;
 }): import("react").JSX.Element;

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

@@ -10,23 +10,28 @@
  * this is an editorial comparison, not a grid.
  *
  * @param {object} props
- * @param {{ label: string, highlight?: boolean }[]} props.columns The first column is
- *   the feature-name column and normally has an empty label.
+ * @param {{ label: string, highlight?: boolean }[]} props.columns
  * @param {{ key?: string, label: string, values: (boolean|import('react').ReactNode)[] }[]} props.rows
- *   `values` aligns with `columns` after the first (feature-name) column.
- * @param {string} [props.caption] Accessible description of what is being compared.
+ * @param {string} [props.caption]
  * @param {string} [props.className]
  */
 export default function AppCompareTable(props: {
+    /** The columns, including the leading capability-name column, whose label is normally empty. */
     columns: {
         label: string;
         highlight?: boolean;
     }[];
+    /** One row per capability. */
     rows: {
         key?: string;
         label: string;
         values: (boolean | import('react').ReactNode)[];
     }[];
+    /** Accessible description of what is being compared. */
     caption?: string;
+    /**
+     * Extra classes on the root.
+     * @default ""
+     */
     className?: string;
 }): import("react").JSX.Element;