@allxsmith/bestax-bulma 5.62.0 → 5.63.0

package/dist/index.esm.js

@@ -44,6 +44,7 @@ export { ToggleButton } from './esm/elements/ToggleButton.js';
 export { Code } from './esm/elements/Code.js';
 export { ColorSwatch } from './esm/elements/ColorSwatch.js';
 export { Content } from './esm/elements/Content.js';
+export { CopyButton } from './esm/elements/CopyButton.js';
 export { Delete } from './esm/elements/Delete.js';
 export { DescriptionList, DescriptionListItem, DescriptionListLabel, DescriptionListValue } from './esm/elements/DescriptionList.js';
 export { Divider } from './esm/elements/Divider.js';
@@ -66,6 +67,8 @@ export { Progress } from './esm/elements/Progress.js';
 export { RingProgress } from './esm/elements/RingProgress.js';
 export { Skeleton } from './esm/elements/Skeleton.js';
 export { Span } from './esm/elements/Span.js';
+export { Stat, StatChange, StatDescription, StatLabel, StatValue } from './esm/elements/Stat.js';
+export { Stats } from './esm/elements/Stats.js';
 export { Strong } from './esm/elements/Strong.js';
 export { SubTitle } from './esm/elements/SubTitle.js';
 export { Table } from './esm/elements/Table.js';
@@ -130,6 +133,7 @@ export { Portal } from './esm/helpers/portal.js';
 export { LocaleProvider, useLocale } from './esm/helpers/LocaleProvider.js';
 export { useNumberFormat } from './esm/helpers/localeFormat.js';
 export { useFocusTrap } from './esm/helpers/useFocusTrap.js';
+export { useClipboard } from './esm/helpers/useClipboard.js';
 export { AppFrame, AppFrameAside, AppFrameBurger, AppFrameFooter, AppFrameHeader, AppFrameMain, AppFrameNav, useAppFrame } from './esm/layout/AppFrame.js';
 export { Center } from './esm/layout/Center.js';
 export { Container } from './esm/layout/Container.js';

package/dist/index.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.esm.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.esm.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/types/elements/Buttons.d.ts

@@ -38,5 +38,6 @@ export declare const Buttons: React.FC<ButtonsProps> & {
     LinkButton: import("../index.js").PolymorphicComponent<import("./LinkButton.js").LinkButtonOwnProps, "button", never>;
     ToggleButton: React.ForwardRefExoticComponent<import("./ToggleButton.js").ToggleButtonProps & React.RefAttributes<HTMLButtonElement>>;
     IconButton: import("../index.js").PolymorphicComponent<import("./IconButton.js").IconButtonOwnProps & import("./IconButton.js").IconButtonName, "button", never>;
+    CopyButton: React.ForwardRefExoticComponent<import("./CopyButton.js").CopyButtonProps & React.RefAttributes<HTMLButtonElement>>;
 };
 export {};

package/dist/types/elements/CopyButton.d.ts

@@ -0,0 +1,105 @@
+import React from 'react';
+import { type ButtonOwnProps } from './Button.js';
+/**
+ * The strings CopyButton shows and announces, each with an English default. A
+ * key left out, or set to an empty string, keeps its default.
+ */
+export interface CopyButtonLabels {
+    /**
+     * The button's label, and so its name, until a copy. With `showLabel` off
+     * it's the name in both states, given as `aria-label`.
+     * @defaultValue 'Copy'
+     */
+    copy?: string;
+    /**
+     * The label shown for `duration` after a copy, and so the name meanwhile.
+     * Not used with `showLabel` off, where only the glyph changes.
+     * @defaultValue 'Copied'
+     */
+    copied?: string;
+    /**
+     * Announced after a copy.
+     * @defaultValue 'Copied to the clipboard'
+     */
+    copiedStatus?: string;
+    /**
+     * Announced when the copy fails.
+     * @defaultValue "Couldn't copy to the clipboard"
+     */
+    failedStatus?: string;
+}
+/**
+ * Props for the CopyButton component. The helper props, the other button
+ * attributes and the `ref` land on the `<button>`.
+ *
+ * @extraProp {'button' | 'submit' | 'reset'} [type=button] - `button` unless you pass `submit` or `reset`.
+ * @extraProp {React.MouseEventHandler<HTMLButtonElement>} [onClick] - Runs before the copy. An `onClick` that calls `preventDefault()` stops the copy, and neither `onCopiedChange` nor `onCopyError` fires.
+ * @extraProp {React.Ref<HTMLButtonElement>} [ref] - Ref forwarded to the `<button>`.
+ */
+export interface CopyButtonProps extends Omit<ButtonOwnProps, 'children'>, Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, keyof ButtonOwnProps | 'value'> {
+    /**
+     * The text it copies. This is not the `<button>`'s form value, which it
+     * doesn't render.
+     */
+    value: string;
+    /**
+     * How long the "Copied" label stays, in milliseconds. Another copy
+     * restarts it. `0` turns the reset off, as Toast's `0` turns off its
+     * auto-close, so "Copied" stays until a later copy fails. A missing or `NaN`
+     * value uses the default, a negative one ends it at once, and `Infinity`,
+     * or anything longer than the longest delay `setTimeout` takes (about 24.8
+     * days), is that longest delay.
+     * @defaultValue 2000
+     */
+    duration?: number;
+    /**
+     * Shows the label beside the icon, which is then the button's name: it
+     * carries no `aria-label`, so the name reads "Copy" and then "Copied" as
+     * the words on it do. Turned off, it's a square icon-only button named by
+     * `labels.copy` through `aria-label` in both states, and only the glyph
+     * changes. An `aria-label` you pass yourself names it in either form.
+     * @defaultValue true
+     */
+    showLabel?: boolean;
+    /** Translations for the label and the announcements. */
+    labels?: CopyButtonLabels;
+    /**
+     * Called with `true` after each copy that worked, a repeat included, and
+     * with `false` when `duration` runs out or a later copy fails.
+     */
+    onCopiedChange?: (copied: boolean) => void;
+    /**
+     * Called when neither the Clipboard API nor the fallback could write. A
+     * copy field can select its text from here, so the reader can copy it
+     * themselves.
+     */
+    onCopyError?: (error: Error) => void;
+}
+/**
+ * The `CopyButton` component renders a button that copies a piece of text to the clipboard, says "Copied" for a moment, and announces the result.
+ *
+ * It's a `Button` with a copy icon and "Copy", and takes everything `Button`
+ * takes. A click writes `value` through the Clipboard API, or through the
+ * older copy command where that's missing or refused, and reports a failure
+ * rather than showing "Copied". Each outcome is announced through a polite
+ * status region portaled out of the button's place, so it stays the last
+ * child of a `Control` or `Buttons`: into the open modal dialog the button is
+ * in, otherwise where `Portal` puts portaled content (the `ConfigProvider`'s
+ * `portalContainer`, or the end of the page). With `showLabel={false}` it's an
+ * `IconButton`. For a trigger of your own, use `useClipboard`, which it's
+ * built on.
+ *
+ * @function
+ * @param {CopyButtonProps} props - Props for the CopyButton component.
+ * @param {React.Ref<HTMLButtonElement>} ref - Forwarded ref to the `<button>`.
+ * @returns {JSX.Element} The rendered button.
+ * @see {@link https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html | WCAG 4.1.3 Status Messages}
+ *
+ * @example
+ * <CopyButton value="https://bestax.io" />
+ *
+ * @example
+ * <CopyButton value={apiKey} showLabel={false} size="small" />
+ */
+export declare const CopyButton: React.ForwardRefExoticComponent<CopyButtonProps & React.RefAttributes<HTMLButtonElement>>;
+export default CopyButton;

package/dist/types/elements/Stat.d.ts

@@ -0,0 +1,242 @@
+import React from 'react';
+import { BulmaClassesProps, validColors } from '../helpers/useBulmaClasses.js';
+/** The colors a Stat's change can take, the union `messageColor` takes. */
+export type StatChangeColor = 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';
+/**
+ * Props for the Stat component. The helper props, the other attributes and
+ * the `ref` land on its root: a `<div>` inside `Stats`, or its own `<dl>` on
+ * its own.
+ *
+ * @extraProp {React.Ref<HTMLElement>} [ref] - Ref forwarded to the root, a `<div>` inside `Stats` or a `<dl>` on its own.
+ */
+export interface StatProps extends Omit<React.HTMLAttributes<HTMLElement>, 'color'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /** Additional CSS classes to apply. */
+    className?: string;
+    /**
+     * What the figure is ("Revenue"), as a `Stat.Label` before the children.
+     * A Stat needs one, here or as a `Stat.Label` child: it's the figure's
+     * name for assistive tech, and a definition list's values belong to a
+     * term. A Stat with neither a `label` nor a `Stat.Label` child warns in
+     * development.
+     */
+    label?: React.ReactNode;
+    /**
+     * The figure, as a `Stat.Value` after the children. A number is written by
+     * `NumberFormatter` with `format` and `locale`; anything else, such as
+     * "N/A", renders as given, and `0` renders. `undefined`, `null`, a boolean
+     * and `''` leave it empty, and its `<dd>` still renders, one line of the
+     * figure tall, while the Stat has a label, so the label keeps its
+     * definition while the figure is missing. A `Stat.Value` child takes its
+     * place: with one, `value` and its `<dd>` are left out.
+     */
+    value?: React.ReactNode;
+    /**
+     * `Intl.NumberFormat` options for a number `value`, as NumberFormatter's
+     * `format`. A `value` that isn't a number ignores it.
+     */
+    format?: Intl.NumberFormatOptions;
+    /**
+     * The locale for `value` and `change`, as NumberFormatter's `locale`.
+     * Unset, it's the `LocaleProvider`'s around it, and with neither, the
+     * runtime's own, so give one, here or through a `LocaleProvider`, on a
+     * page rendered on the server.
+     */
+    locale?: string;
+    /**
+     * The change, as a `Stat.Change` after the value. With the default format
+     * it's a fraction (`0.12` for 12%); with your own `changeFormat`, it's in
+     * that format's terms. It's written with its sign, so the direction is in
+     * the text.
+     */
+    change?: number;
+    /**
+     * `Intl.NumberFormat` options for `change`. Yours replace the default, and
+     * `signDisplay: 'exceptZero'` is added unless you set a `signDisplay`. With
+     * `signDisplay: 'never'`, or `'negative'` on a rise, the text carries no
+     * direction: the arrow is hidden from assistive tech and the tone is color
+     * alone, so keep a sign, or say the direction in `description`.
+     * @defaultValue { style: 'percent', signDisplay: 'exceptZero', maximumFractionDigits: 1 }
+     */
+    changeFormat?: Intl.NumberFormatOptions;
+    /**
+     * The change's color. Unset, it's the sign's: `success` up, `danger` down,
+     * and none at zero. Set it where up is bad news, such as a cost or an
+     * error rate.
+     */
+    changeColor?: StatChangeColor;
+    /** A note under the figure ("since last month"), as a `Stat.Description` last. */
+    description?: React.ReactNode;
+    /**
+     * The figure's size, a step of Bulma's size scale. The label, the change
+     * and the note stay small.
+     */
+    size?: 'small' | 'medium' | 'large';
+    /**
+     * Shows a `Skeleton` in place of `value`, one line of the figure tall,
+     * and sets `aria-busy` on the Stat. The label, the change and the note
+     * render as given. With a `Stat.Value` child, it only sets `aria-busy`:
+     * the child renders as given, so put a `Skeleton` in it yourself.
+     */
+    loading?: boolean;
+    /**
+     * `Stat.Label`, `Stat.Value`, `Stat.Change` and `Stat.Description`, for
+     * anything the props don't cover, such as a unit or an info tip. They
+     * render between `label` and `value`. They're this Stat's own parts, so
+     * not another Stat: that would be a list inside this one's. The Stat finds
+     * a `Stat.Label` or `Stat.Value` among them by type, so one rendered from
+     * inside a component of your own isn't seen.
+     */
+    children?: React.ReactNode;
+    /**
+     * Text color helper. It colors the figure; the label, the change and the
+     * note keep their own colors. Inside `Stats`, a Stat without one takes the
+     * row's.
+     */
+    textColor?: (typeof validColors)[number] | 'inherit' | 'current';
+    /** Background color helper. */
+    bgColor?: (typeof validColors)[number] | 'inherit' | 'current';
+}
+/**
+ * Props for Stat.Label, what the figure is. The helper props, the other
+ * attributes and the `ref` land on its `<dt>`.
+ *
+ * @extraProp {React.Ref<HTMLElement>} [ref] - Ref forwarded to the `<dt>`.
+ */
+export interface StatLabelProps extends Omit<React.HTMLAttributes<HTMLElement>, 'color'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /** Additional CSS classes to apply. */
+    className?: string;
+    /**
+     * The label. A button may sit in it, such as one that opens a `Popover`
+     * about the figure, but not a heading, which HTML doesn't allow here.
+     */
+    children?: React.ReactNode;
+    /** Text color helper. */
+    textColor?: (typeof validColors)[number] | 'inherit' | 'current';
+    /** Background color helper. */
+    bgColor?: (typeof validColors)[number] | 'inherit' | 'current';
+}
+/**
+ * Props for Stat.Value, the figure. The helper props, the other attributes
+ * and the `ref` land on its `<dd>`.
+ *
+ * @extraProp {React.Ref<HTMLElement>} [ref] - Ref forwarded to the `<dd>`.
+ */
+export interface StatValueProps extends Omit<React.HTMLAttributes<HTMLElement>, 'color'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /** Additional CSS classes to apply. */
+    className?: string;
+    /**
+     * The figure, written as you give it, so write a number with
+     * `NumberFormatter`.
+     */
+    children?: React.ReactNode;
+    /** Text color helper. */
+    textColor?: (typeof validColors)[number] | 'inherit' | 'current';
+    /** Background color helper. */
+    bgColor?: (typeof validColors)[number] | 'inherit' | 'current';
+}
+/**
+ * Props for Stat.Description, a note under the figure. The helper props, the
+ * other attributes and the `ref` land on its `<dd>`.
+ *
+ * @extraProp {React.Ref<HTMLElement>} [ref] - Ref forwarded to the `<dd>`.
+ */
+export interface StatDescriptionProps extends Omit<React.HTMLAttributes<HTMLElement>, 'color'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /** Additional CSS classes to apply. */
+    className?: string;
+    /** The note, such as "since last month". */
+    children?: React.ReactNode;
+    /** Text color helper. */
+    textColor?: (typeof validColors)[number] | 'inherit' | 'current';
+    /** Background color helper. */
+    bgColor?: (typeof validColors)[number] | 'inherit' | 'current';
+}
+/**
+ * Props for Stat.Change, a change written with its sign. The helper props,
+ * the other attributes and the `ref` land on its `<dd>`.
+ *
+ * @extraProp {React.Ref<HTMLElement>} [ref] - Ref forwarded to the `<dd>`.
+ */
+export interface StatChangeProps extends Omit<React.HTMLAttributes<HTMLElement>, 'color' | 'children'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /** Additional CSS classes to apply. */
+    className?: string;
+    /**
+     * The change, as Stat's `change`. One that rounds to zero in its format,
+     * such as `0.0004` at one decimal place of a percentage, reads as zero, so
+     * it gets no arrow and no color of its own.
+     */
+    value: number;
+    /**
+     * As Stat's `changeFormat`: yours replace the default, and
+     * `signDisplay: 'exceptZero'` is added unless you set a `signDisplay`.
+     * @defaultValue { style: 'percent', signDisplay: 'exceptZero', maximumFractionDigits: 1 }
+     */
+    format?: Intl.NumberFormatOptions;
+    /** As Stat's `locale`. Unset, the Stat's. */
+    locale?: string;
+    /**
+     * As Stat's `changeColor`. Unset, it's the sign's: `success` up, `danger`
+     * down, and none at zero. Set, it applies at zero too.
+     */
+    color?: StatChangeColor;
+}
+/**
+ * What the figure is: a `<dt>`, small and in the weaker text color.
+ *
+ * @function
+ * @param {StatLabelProps} props - Props for Stat.Label.
+ * @param {React.Ref<HTMLElement>} ref - Forwarded ref to the `<dt>`.
+ * @returns {JSX.Element} The rendered label.
+ *
+ * @example
+ * <Stat.Label>Revenue</Stat.Label>
+ */
+export declare const StatLabel: React.ForwardRefExoticComponent<StatLabelProps & React.RefAttributes<HTMLElement>>;
+/**
+ * The figure: a `<dd>`, large, in the Stat's color, with digits of one width so a figure that updates doesn't shift.
+ *
+ * @function
+ * @param {StatValueProps} props - Props for Stat.Value.
+ * @param {React.Ref<HTMLElement>} ref - Forwarded ref to the `<dd>`.
+ * @returns {JSX.Element} The rendered figure.
+ *
+ * @example
+ * <Stat.Value>
+ *   <NumberFormatter value={182} format={{ style: 'unit', unit: 'millisecond' }} />
+ * </Stat.Value>
+ */
+export declare const StatValue: React.ForwardRefExoticComponent<StatValueProps & React.RefAttributes<HTMLElement>>;
+/**
+ * A note under the figure: a `<dd>`, small and in the weaker text color.
+ *
+ * @function
+ * @param {StatDescriptionProps} props - Props for Stat.Description.
+ * @param {React.Ref<HTMLElement>} ref - Forwarded ref to the `<dd>`.
+ * @returns {JSX.Element} The rendered note.
+ *
+ * @example
+ * <Stat.Description>since last month</Stat.Description>
+ */
+export declare const StatDescription: React.ForwardRefExoticComponent<StatDescriptionProps & React.RefAttributes<HTMLElement>>;
+/**
+ * A change written with its sign, such as "+12%", after an arrow that repeats the direction: a `<dd>`, green when it's up and red when it's down unless `color` says otherwise.
+ *
+ * The sign is in the text, written by `Intl` for the locale, so a screen
+ * reader hears the direction; the arrow is hidden from assistive tech, and
+ * the color repeats the direction for sighted readers rather than carry it.
+ *
+ * @function
+ * @param {StatChangeProps} props - Props for Stat.Change.
+ * @param {React.Ref<HTMLElement>} ref - Forwarded ref to the `<dd>`.
+ * @returns {JSX.Element} The rendered change.
+ *
+ * @example
+ * <Stat.Change value={-0.08} color="success" />
+ */
+export declare const StatChange: React.ForwardRefExoticComponent<StatChangeProps & React.RefAttributes<HTMLElement>>;
+export declare const Stat: React.ForwardRefExoticComponent<StatProps & React.RefAttributes<HTMLElement>> & {
+    Label: React.ForwardRefExoticComponent<StatLabelProps & React.RefAttributes<HTMLElement>>;
+    Value: React.ForwardRefExoticComponent<StatValueProps & React.RefAttributes<HTMLElement>>;
+    Change: React.ForwardRefExoticComponent<StatChangeProps & React.RefAttributes<HTMLElement>>;
+    Description: React.ForwardRefExoticComponent<StatDescriptionProps & React.RefAttributes<HTMLElement>>;
+};
+export default Stat;

package/dist/types/elements/Stats.d.ts

@@ -0,0 +1,40 @@
+import React from 'react';
+import { BulmaClassesProps, validColors } from '../helpers/useBulmaClasses.js';
+import type { BulmaMinColValue } from '../grid/Grid.js';
+/**
+ * Props for the Stats component, a row of Stats on Bulma's smart grid. The
+ * helper props, the other attributes and the `ref` land on its `<dl>`.
+ *
+ * @extraProp {React.Ref<HTMLDListElement>} [ref] - Ref forwarded to the `<dl>`.
+ * @extraProp {BulmaGapStep} [gap] - The space between tiles (`is-gap-*`), the helper prop with the values Grid's `gap` takes.
+ * @extraProp {string} [aria-labelledby] - The id of the heading above the row, which names it.
+ */
+export interface StatsProps extends Omit<React.HTMLAttributes<HTMLDListElement>, 'color'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /** Additional CSS classes to apply. */
+    className?: string;
+    /** `Stat`s, one per figure, and nothing else: they're the groups of its `<dl>`. */
+    children?: React.ReactNode;
+    /**
+     * The narrowest a tile gets before the row wraps (`is-col-min-*`), as
+     * Grid's `minCol`: 1.5rem a step. Unset, it's Bulma's 9rem.
+     */
+    minCol?: BulmaMinColValue;
+    /**
+     * Text color helper: `has-text-*` on the `<dl>`, as on Buttons. Each Stat
+     * in the row without a `textColor` of its own takes it too, which colors
+     * its figure, since a Stat sets its own color. The labels, the changes and
+     * the notes keep theirs.
+     */
+    textColor?: (typeof validColors)[number] | 'inherit' | 'current';
+    /** Background color helper. */
+    bgColor?: (typeof validColors)[number] | 'inherit' | 'current';
+}
+export declare const Stats: React.ForwardRefExoticComponent<StatsProps & React.RefAttributes<HTMLDListElement>> & {
+    Stat: React.ForwardRefExoticComponent<import("./Stat.js").StatProps & React.RefAttributes<HTMLElement>> & {
+        Label: React.ForwardRefExoticComponent<import("./Stat.js").StatLabelProps & React.RefAttributes<HTMLElement>>;
+        Value: React.ForwardRefExoticComponent<import("./Stat.js").StatValueProps & React.RefAttributes<HTMLElement>>;
+        Change: React.ForwardRefExoticComponent<import("./Stat.js").StatChangeProps & React.RefAttributes<HTMLElement>>;
+        Description: React.ForwardRefExoticComponent<import("./Stat.js").StatDescriptionProps & React.RefAttributes<HTMLElement>>;
+    };
+};
+export default Stats;

package/dist/types/elements/statContext.d.ts

@@ -0,0 +1,18 @@
+import type { validColors } from '../helpers/useBulmaClasses.js';
+export interface StatScope {
+    /**
+     * Whether this is inside a `Stats` row, where a Stat is a `<div>` in the
+     * row's `<dl>` rather than a `<dl>` of its own. A Stat sets it back to
+     * `false` for its children. Those are meant to be its parts, so a Stat
+     * inside a part sits in a `<dd>`, where a `<dl>` of its own is valid. A
+     * Stat written straight among another's children isn't handled: it renders
+     * a `<dl>` inside the other's list, which HTML doesn't allow, and Stat's
+     * `children` TSDoc says not to.
+     */
+    row: boolean;
+    /** The row's `textColor`, which each Stat in it takes unless it has its own. */
+    textColor?: (typeof validColors)[number] | 'inherit' | 'current';
+    /** The Stat's `locale`, which a `Stat.Change` in it takes unless it has its own. */
+    locale?: string;
+}
+export declare const StatScopeContext: import("react").Context<StatScope>;

package/dist/types/helpers/checkIcon.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A check mark, 1em square and drawn in `currentColor`, so it takes the text
+ * color around it, the system's in forced colors included. Combobox draws it
+ * beside a chosen item, and CopyButton after a copy. It's decorative: put it
+ * inside something `aria-hidden`.
+ *
+ * @function CheckIcon
+ * @returns The check mark's `<svg>`.
+ */
+export declare function CheckIcon(): import("react").JSX.Element;

package/dist/types/helpers/isGiven.d.ts

@@ -0,0 +1,7 @@
+import type { ReactNode } from 'react';
+/**
+ * INTERNAL, deliberately not exported from `src/index.ts`. Whether a prop
+ * was given something to render: `undefined`, `null`, a boolean and `''`
+ * weren't, and `0` was, since React renders it.
+ */
+export declare const isGiven: (node: ReactNode) => boolean;

package/dist/types/helpers/useClipboard.d.ts

@@ -0,0 +1,65 @@
+/** Options for useClipboard. */
+export interface UseClipboardOptions {
+    /**
+     * How long `copied` stays `true` after a copy, in milliseconds. Another
+     * copy restarts it. `0` turns the timer off, as Toast's `0` does, so
+     * `copied` stays `true` until a later copy fails. A missing or `NaN` value
+     * uses the default, a negative one ends it at once, and `Infinity`, or
+     * anything longer than the longest delay `setTimeout` takes (2147483647 ms,
+     * about 24.8 days), is that longest delay.
+     * @defaultValue 2000
+     */
+    duration?: number;
+    /**
+     * Called with `true` after each copy that worked, a repeat included, and
+     * with `false` when `duration` runs out or a later copy fails.
+     */
+    onCopiedChange?: (copied: boolean) => void;
+    /**
+     * Called when neither the Clipboard API nor the copy command could write,
+     * with the Clipboard API's own error when it refused, or an `Error` saying
+     * neither could.
+     */
+    onCopyError?: (error: Error) => void;
+}
+/** What useClipboard returns. */
+export interface UseClipboardResult {
+    /**
+     * Writes `text` to the clipboard, and resolves `true` once it's written or
+     * `false` when it couldn't be. It never rejects. Call it from a click or a
+     * key press, with no `await` before it: browsers only allow a write
+     * shortly after one. A call that a later one overtakes leaves `copied`,
+     * `error` and the callbacks to the later one, and doesn't fall back to the
+     * copy command once the later one has started.
+     */
+    copy: (text: string) => Promise<boolean>;
+    /**
+     * `true` for `duration` after a copy that worked, or, with a `duration` of
+     * `0`, until a later copy fails.
+     */
+    copied: boolean;
+    /** Why the last copy failed, or `null` after one that worked. */
+    error: Error | null;
+}
+/**
+ * Copies text to the clipboard through the Clipboard API, falling back to the copy command where that's missing or refused, and keeps a `copied` flag for `duration` after a copy.
+ *
+ * It announces nothing. A trigger of your own says "Copied" in a
+ * `role="status"` region that's in the page before the click; `CopyButton`
+ * is this hook with the button, the label and the announcement built in.
+ *
+ * A failed copy sets `error`, calls `onCopyError`, and ends `copied` if a
+ * copy before it had set it. When copies overlap, only the latest one's
+ * outcome sets the state and fires the callbacks, whichever finishes first.
+ * Nothing changes and no callback fires once the component using it has
+ * unmounted, though a write already under way still finishes.
+ *
+ * @function useClipboard
+ * @param options - How long `copied` lasts, and the callbacks.
+ * @returns `copy`, which writes, and the `copied` and `error` state.
+ *
+ * @example
+ * const { copy, copied } = useClipboard();
+ * <Button onClick={() => copy(url)}>{copied ? 'Copied' : 'Copy link'}</Button>
+ */
+export declare function useClipboard(options?: UseClipboardOptions): UseClipboardResult;

package/dist/types/index.d.ts

@@ -43,6 +43,7 @@ export * from './elements/ToggleButton.js';
 export * from './elements/Code.js';
 export * from './elements/ColorSwatch.js';
 export * from './elements/Content.js';
+export * from './elements/CopyButton.js';
 export * from './elements/Delete.js';
 export * from './elements/DescriptionList.js';
 export * from './elements/Divider.js';
@@ -65,6 +66,8 @@ export * from './elements/Progress.js';
 export * from './elements/RingProgress.js';
 export * from './elements/Skeleton.js';
 export * from './elements/Span.js';
+export * from './elements/Stat.js';
+export * from './elements/Stats.js';
 export * from './elements/Strong.js';
 export * from './elements/SubTitle.js';
 export * from './elements/Table.js';
@@ -152,6 +155,8 @@ export { useNumberFormat } from './helpers/localeFormat.js';
 export type { NumberFormatFunction } from './helpers/localeFormat.js';
 export { useFocusTrap } from './helpers/useFocusTrap.js';
 export type { UseFocusTrapOptions } from './helpers/useFocusTrap.js';
+export { useClipboard } from './helpers/useClipboard.js';
+export type { UseClipboardOptions, UseClipboardResult, } from './helpers/useClipboard.js';
 export * from './layout/AppFrame.js';
 export * from './layout/Center.js';
 export * from './layout/Container.js';

package/dist/types-cjs/elements/Buttons.d.ts

@@ -38,5 +38,6 @@ export declare const Buttons: React.FC<ButtonsProps> & {
     LinkButton: import("../index.js").PolymorphicComponent<import("./LinkButton.js").LinkButtonOwnProps, "button", never>;
     ToggleButton: React.ForwardRefExoticComponent<import("./ToggleButton.js").ToggleButtonProps & React.RefAttributes<HTMLButtonElement>>;
     IconButton: import("../index.js").PolymorphicComponent<import("./IconButton.js").IconButtonOwnProps & import("./IconButton.js").IconButtonName, "button", never>;
+    CopyButton: React.ForwardRefExoticComponent<import("./CopyButton.js").CopyButtonProps & React.RefAttributes<HTMLButtonElement>>;
 };
 export {};