@allxsmith/bestax-bulma 5.62.0 → 5.64.0

package/dist/types/form/PasswordInputBase.d.ts

@@ -0,0 +1,91 @@
+import { InputBaseProps } from './InputBase.js';
+/** How PasswordInput's visibility toggle draws itself. */
+export type PasswordInputVariant = 'icon' | 'text';
+/** The strings PasswordInput's toggle shows and announces, for translating. */
+export interface PasswordInputLabels {
+    /**
+     * The toggle's name. With the `icon` variant it's the name in both states,
+     * and `aria-pressed` says whether the password shows. With `text`, it's the
+     * name while the password is hidden, and it has to contain `show`, the word
+     * on the button.
+     * @defaultValue 'Show password'
+     */
+    showPassword?: string;
+    /**
+     * The `text` variant's name while the password shows. It has to contain
+     * `hide`.
+     * @defaultValue 'Hide password'
+     */
+    hidePassword?: string;
+    /**
+     * The `text` variant's word while the password is hidden.
+     * @defaultValue 'Show'
+     */
+    show?: string;
+    /**
+     * The `text` variant's word while the password shows.
+     * @defaultValue 'Hide'
+     */
+    hide?: string;
+}
+/**
+ * Props for PasswordInputBase, the input and its toggle without a Field or a
+ * Control.
+ *
+ * @helperProps Helper props go on the `.password-input-container` `<div>`, with
+ * `className` and `style`, so they move and size the field and its toggle
+ * together. The other attributes go on the `<input>`.
+ * @extraProp {string} [autoComplete="current-password"] - Tells the browser and password managers this is an existing password. Pass `"new-password"` where the user makes one up, on a sign-up or change-password form.
+ * @extraProp {boolean} [spellCheck=false] - Off, so a browser's spellcheck never sees the password once it shows.
+ * @extraProp {string} [autoCorrect="off"] - Off, so a phone's keyboard doesn't change what's typed.
+ * @extraProp {string} [autoCapitalize="none"] - Off, so a phone's keyboard doesn't capitalize the first letter.
+ * @extraProp {string} [value] - The password, controlled. React writes a controlled input's value into its `value` attribute, as it does on any input, so the password sits in the page's markup. Uncontrolled, read with `FormData`, the field never puts what's typed there.
+ * @extraProp {React.Ref<HTMLInputElement>} [ref] - Ref forwarded to the `<input>`.
+ */
+export interface PasswordInputBaseProps extends Omit<InputBaseProps, 'type'> {
+    /**
+     * Whether the password shows, when you hold the state. Setting it makes
+     * the visibility controlled: the toggle only calls `onVisibleChange`, and
+     * so does hiding again on its own. Apply that `false` and the field is a
+     * password field by the time the form reads it; keep `visible` true and
+     * the field stays shown.
+     */
+    visible?: boolean;
+    /**
+     * Whether the password shows at first, when the input holds its own state.
+     * @defaultValue false
+     */
+    defaultVisible?: boolean;
+    /**
+     * Called with the new visibility on each toggle, and with `false` when the
+     * form submits or resets, or the page is left, which it also is on the way
+     * into the back-forward cache. React renders those hides at once, a state
+     * update you make here included, so the form reads a password field. One
+     * that fires while React is rendering or committing, which includes your
+     * `useEffect` and `useLayoutEffect` callbacks, such as a `requestSubmit()`
+     * from an effect, can't render there, and lands just after the form is
+     * read: hide the password first, or submit from an event handler.
+     */
+    onVisibleChange?: (visible: boolean) => void;
+    /**
+     * How the toggle draws itself: an eye icon with a fixed name and
+     * `aria-pressed`, or the words "Show" and "Hide" with a name that follows
+     * them.
+     * @defaultValue 'icon'
+     */
+    variant?: PasswordInputVariant;
+    /** Translations for the toggle. */
+    labels?: PasswordInputLabels;
+}
+/**
+ * The raw PasswordInput: a password field with a button inside it that shows what was typed, without Field/Control wrapping.
+ *
+ * Use `PasswordInput` for the convenience wrapper.
+ *
+ * @function
+ * @param {PasswordInputBaseProps} props - Props for PasswordInputBase.
+ * @param {React.Ref<HTMLInputElement>} ref - Forwarded ref to the `<input>`.
+ * @returns {JSX.Element} The input and its toggle, in a container.
+ */
+export declare const PasswordInputBase: import("react").ForwardRefExoticComponent<PasswordInputBaseProps & import("react").RefAttributes<HTMLInputElement>>;
+export default PasswordInputBase;

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/helpers/useScrollSpy.d.ts

@@ -0,0 +1,61 @@
+/** Options for useScrollSpy. */
+export interface UseScrollSpyOptions {
+    /**
+     * **Required.** The ids of the sections to watch, without the `#`, in the
+     * order they come on the page. Each one is looked up each time the hook
+     * checks, so an id with no element on the page is skipped until one
+     * appears, and a section replaced under the same id keeps working.
+     */
+    ids: string[];
+    /**
+     * Pixels from the viewport's top where a section counts as reached. Unset,
+     * it's the page's `scroll-padding-top`, read when the hook mounts and on
+     * resize, so the highlight agrees with where a jump lands under a sticky
+     * header. A `scroll-padding-top` that mixes a percentage with a length in
+     * `calc()` isn't read: pass `offset` then.
+     */
+    offset?: number;
+    /** Called with the new current id when it changes, or `null` above the first section. */
+    onCurrentChange?: (id: string | null) => void;
+}
+/**
+ * The `useScrollSpy` hook returns the id of the section being read: the last
+ * of `ids` whose top is at or above the offset line, or the last one once the
+ * page is scrolled to its end. After a jump to one of them, it's that one
+ * until the reader scrolls on. `null` above the first section, on the server
+ * and until the page hydrates.
+ *
+ * It checks once per frame while the page scrolls, and on resize. A jump is
+ * a plain click on a link to one of the ids (the main button, no modifier
+ * key, opening in this page), noted and never stopped, so the browser jumps
+ * as it always does; and the `#id` a page opened afresh opens at. Back,
+ * Forward and a reload aren't jumps. That `#id` is read once, when `ids`
+ * first has some: a section rendered after that isn't held, even if the
+ * page opened at it, and the reading rule marks where the page is. Once the
+ * page has been still for a
+ * moment, the section stays current only if it's where a jump puts it: its
+ * top at the line, give or take a shift of the layout smaller than its own
+ * height, or, at the end of the page, on screen below the line. Otherwise,
+ * as after a flick right after the click, the reading rule takes over. The
+ * next scroll after that lets it go, the browser's own included, so when
+ * content loading above it makes the browser scroll to keep the reader's
+ * place, the rule takes over too.
+ *
+ * A section that isn't drawn (`display: none`) is never current. A section
+ * that moves while nothing scrolls is seen at the next scroll or resize. It
+ * watches the document only: not a panel that scrolls inside it, and not
+ * sections inside a shadow root, which an `#id` link can't reach either.
+ * Whether a page was opened afresh is read from how the document loaded, so
+ * in an app that changes routes on the client, a route change can briefly
+ * mark the address bar's section until the page settles, when the reading
+ * rule takes over, and after a reload a route change to an `#id` holds
+ * nothing.
+ *
+ * @function
+ * @param {UseScrollSpyOptions} options - The ids to watch, the offset, and a change callback.
+ * @returns {string | null} The current section's id, or `null`.
+ *
+ * @example
+ * const current = useScrollSpy({ ids: ['profile', 'security', 'billing'] });
+ */
+export declare function useScrollSpy({ ids, offset, onCurrentChange, }: UseScrollSpyOptions): string | null;

package/dist/types/index.d.ts

@@ -34,6 +34,7 @@ export * from './components/ScrollArea.js';
 export * from './components/Command.js';
 export * from './components/DataTable.js';
 export * from './components/Affix.js';
+export * from './components/TableOfContents.js';
 export * from './elements/Block.js';
 export * from './elements/Box.js';
 export * from './elements/Button.js';
@@ -43,6 +44,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 +67,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';
@@ -105,12 +109,16 @@ export { SelectBase } from './form/SelectBase.js';
 export type { SelectBaseProps } from './form/SelectBase.js';
 export { TextAreaBase } from './form/TextAreaBase.js';
 export type { TextAreaBaseProps } from './form/TextAreaBase.js';
+export { PasswordInputBase } from './form/PasswordInputBase.js';
+export type { PasswordInputBaseProps, PasswordInputLabels, PasswordInputVariant, } from './form/PasswordInputBase.js';
 export { Input } from './form/Input.js';
 export type { InputProps } from './form/Input.js';
 export { Select } from './form/Select.js';
 export type { SelectProps } from './form/Select.js';
 export { TextArea } from './form/TextArea.js';
 export type { TextAreaProps } from './form/TextArea.js';
+export { PasswordInput } from './form/PasswordInput.js';
+export type { PasswordInputProps } from './form/PasswordInput.js';
 export { DateInputBase } from './form/DateInputBase.js';
 export type { DateInputBaseProps } from './form/DateInputBase.js';
 export { DateInput } from './form/DateInput.js';
@@ -152,6 +160,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/components/TableOfContents.d.ts

@@ -0,0 +1,87 @@
+import React from 'react';
+import { BulmaClassesProps, validColors } from '../helpers/useBulmaClasses.js';
+export { useScrollSpy } from '../helpers/useScrollSpy.js';
+export type { UseScrollSpyOptions } from '../helpers/useScrollSpy.js';
+/** One entry in a TableOfContents. */
+export interface TableOfContentsItem {
+    /** **Required.** The `id` of the section or heading it links to, without the `#`. Unique on the page. */
+    id: string;
+    /** **Required.** What the link says, usually the heading's own text. */
+    label: React.ReactNode;
+    /** Entries under this one, drawn as a nested list. */
+    children?: TableOfContentsItem[];
+}
+/** The visible strings, in your app's language. */
+export interface TableOfContentsLabels {
+    /**
+     * The list's visible title, which also names its `<nav>`.
+     * @defaultValue 'On this page'
+     */
+    title?: string;
+}
+/**
+ * Props for the TableOfContents component. The helper props, the other
+ * attributes and the `ref` land on the `<nav>`.
+ *
+ * @extraProp {React.Ref<HTMLElement>} [ref] - Ref forwarded to the `<nav>`.
+ */
+export interface TableOfContentsProps extends Omit<React.HTMLAttributes<HTMLElement>, 'color' | 'children'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /** Additional CSS classes to apply. */
+    className?: string;
+    /**
+     * **Required.** The sections, in page order, as links to their ids. Each
+     * link is a plain `<a href="#id">`, so following one is the browser's own
+     * jump: put `scroll-padding-top` on the page to land clear of a sticky
+     * header, and smooth scrolling, if you want it, in page CSS inside
+     * `@media (prefers-reduced-motion: no-preference)`.
+     */
+    items: TableOfContentsItem[];
+    /**
+     * Called with the current section's id when it changes, or `null` above
+     * the first section. Never called on the server or before hydration.
+     */
+    onCurrentChange?: (id: string | null) => void;
+    /**
+     * Pixels from the viewport's top where a section counts as reached.
+     * Unset, it's the page's `scroll-padding-top`, so the highlight agrees
+     * with where a jump lands under a sticky header.
+     */
+    offset?: number;
+    /**
+     * Sticks to the top of the viewport as the page scrolls, at
+     * `--bulma-table-of-contents-sticky-top`, and scrolls itself when it's
+     * taller than the viewport. Adds `is-sticky`.
+     */
+    isSticky?: boolean;
+    /** The visible strings, in your app's language. */
+    labels?: TableOfContentsLabels;
+    /** Text color helper. */
+    textColor?: (typeof validColors)[number] | 'inherit' | 'current';
+    /** Background color helper. */
+    bgColor?: (typeof validColors)[number] | 'inherit' | 'current';
+}
+/**
+ * The `TableOfContents` component lists a long page's sections as links in Bulma's menu look, and marks the one being read.
+ *
+ * It's a `<nav>` named by its title, holding `MenuList` and `MenuItem` links
+ * to each `#id`, rendered in full on the server. `useScrollSpy` picks the
+ * current section, and its link alone gets `is-active` and
+ * `aria-current="location"`. Use the hook on its own to mark the section in
+ * view somewhere else, such as an app's nav `Menu`.
+ *
+ * @function
+ * @param {TableOfContentsProps} props - Props for the TableOfContents component.
+ * @param {React.Ref<HTMLElement>} ref - Forwarded ref to the `<nav>`.
+ * @returns {JSX.Element} The rendered table of contents.
+ *
+ * @example
+ * <TableOfContents
+ *   isSticky
+ *   items={[
+ *     { id: 'install', label: 'Install' },
+ *     { id: 'usage', label: 'Usage', children: [{ id: 'props', label: 'Props' }] },
+ *   ]}
+ * />
+ */
+export declare const TableOfContents: React.ForwardRefExoticComponent<TableOfContentsProps & React.RefAttributes<HTMLElement>>;
+export default TableOfContents;

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 {};

package/dist/types-cjs/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;