@allxsmith/bestax-bulma 5.33.1 → 5.34.0

package/dist/index.esm.js

@@ -7,6 +7,7 @@ export { Badge } from './esm/components/Badge.js';
 export { Breadcrumb } from './esm/components/Breadcrumb.js';
 export { Card } from './esm/components/Card.js';
 export { Dropdown, DropdownDivider, DropdownItem, isBrowser } from './esm/components/Dropdown.js';
+export { EmptyState, EmptyStateActions, EmptyStateDescription, EmptyStateIndicator, EmptyStateTitle } from './esm/components/EmptyState.js';
 export { Menu, MenuItem, MenuLabel, MenuList } from './esm/components/Menu.js';
 export { Message } from './esm/components/Message.js';
 export { Modal } from './esm/components/Modal.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/components/EmptyState.d.ts

@@ -0,0 +1,149 @@
+import React from 'react';
+import { BulmaClassesProps, validColors } from '../helpers/useBulmaClasses.js';
+import { ButtonsProps } from '../elements/Buttons.js';
+import { ParagraphProps } from '../elements/Paragraph.js';
+import { TitleProps } from '../elements/Title.js';
+declare const validEmptyStateColors: readonly ["primary", "link", "info", "success", "warning", "danger"];
+/** The Bulma colors the indicator takes. */
+export type EmptyStateColor = (typeof validEmptyStateColors)[number];
+declare const validEmptyStateHeadings: readonly ["h1", "h2", "h3", "h4", "h5", "h6"];
+/** A title's heading level. It's always a heading, so there's no `p`. */
+export type EmptyStateHeading = (typeof validEmptyStateHeadings)[number];
+/**
+ * Props for the EmptyState component. The helper props, the other attributes
+ * and the `ref` land on the root `<div>`. The native `title` attribute isn't
+ * one of them, since `title` here is the heading.
+ *
+ * @extraProp {React.Ref<HTMLDivElement>} [ref] - Ref forwarded to the root `<div>`.
+ */
+export interface EmptyStateProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'color' | 'title'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /** Additional CSS classes to apply. */
+    className?: string;
+    /**
+     * The picture in the indicator's circle. A string is an `Icon` name, drawn
+     * from the icon library `ConfigProvider` sets. Anything else (an `<Icon>`
+     * with its own `variant` or `library`, an SVG, an `<img>`) renders as it is.
+     * It's decorative and hidden from assistive tech, so the title says what
+     * it means.
+     */
+    icon?: React.ReactNode;
+    /**
+     * The heading, rendered as `EmptyState.Title`. It's always a real heading,
+     * at the level `titleAs` sets.
+     */
+    title?: React.ReactNode;
+    /**
+     * The heading level for `title`: the level under the heading of the list
+     * it stands in for, such as `h3` for a list under an `h2`. Only this sets
+     * the level, and the size comes from `size`.
+     */
+    titleAs?: EmptyStateHeading;
+    /** A sentence or two under the title, rendered as `EmptyState.Description`. */
+    description?: React.ReactNode;
+    /**
+     * Rendered as written, after whatever `icon`, `title` and `description`
+     * render. One button can go straight in, and it sits centered under the
+     * text. Group two or more in `EmptyState.Actions`, or they stack. Without
+     * the props, write the parts here in the order they're shown:
+     * `EmptyState.Indicator`, `.Title`, `.Description`, then the actions.
+     */
+    children?: React.ReactNode;
+    /**
+     * The indicator's color. It colors the circle and its icon, not the text.
+     * Without it the circle is neutral, since an empty list isn't a status.
+     */
+    color?: EmptyStateColor;
+    /**
+     * `light` is a soft tint of `color` behind the icon in the color. `filled`
+     * is the color itself, with the icon in its invert.
+     */
+    variant?: 'light' | 'filled';
+    /** Sizes the indicator, the title, the description and the spacing together. */
+    size?: 'small' | 'normal' | 'medium' | 'large';
+    /**
+     * `center` stacks everything in a centered column. `left` puts the
+     * indicator beside the text, at the start of the line, so on the right in
+     * a right-to-left page, and keeps the block at least as tall as the circle
+     * whatever block padding is in effect. Without an indicator, it only puts
+     * the text at the start of the line. In `left`, the padding at the start
+     * of the line is what makes room for the indicator, so pad it with `py`
+     * rather than `p` or `px`.
+     */
+    align?: 'center' | 'left';
+    /** Text color helper. */
+    textColor?: (typeof validColors)[number] | 'inherit' | 'current';
+    /** Background color helper. */
+    bgColor?: (typeof validColors)[number] | 'inherit' | 'current';
+}
+/** Props for EmptyState.Indicator, the circle the picture sits in. */
+export interface EmptyStateIndicatorProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'color'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /** Additional CSS classes to apply. */
+    className?: string;
+    /**
+     * The picture: an `Icon`, an SVG or an `<img>`. The indicator is hidden
+     * from assistive tech, an `Icon` with an `ariaLabel` included, so anything
+     * it means goes in the title or the description.
+     */
+    children?: React.ReactNode;
+    /** Text color helper. */
+    textColor?: (typeof validColors)[number] | 'inherit' | 'current';
+    /** Background color helper. */
+    bgColor?: (typeof validColors)[number] | 'inherit' | 'current';
+}
+/**
+ * Props for EmptyState.Title. It renders `Title` with `as` and never `size`,
+ * so the level is `as` alone and the size comes from the EmptyState.
+ */
+export interface EmptyStateTitleProps extends Omit<TitleProps, 'as' | 'size' | 'isSpaced'> {
+    /**
+     * The heading level: the level under the heading of the list the empty
+     * state stands in for.
+     */
+    as?: EmptyStateHeading;
+}
+/** Props for EmptyState.Description, a `<p>` under the title. */
+export type EmptyStateDescriptionProps = ParagraphProps;
+/**
+ * Props for EmptyState.Actions, the row of buttons. It renders `Buttons`,
+ * and the EmptyState aligns it, so `isCentered` and `isRight` are left out.
+ */
+export type EmptyStateActionsProps = Omit<ButtonsProps, 'isCentered' | 'isRight'>;
+/**
+ * The circle the picture sits in, hidden from assistive tech whatever is in it.
+ *
+ * @function
+ * @param {EmptyStateIndicatorProps} props - Props for EmptyState.Indicator.
+ * @returns {JSX.Element} The rendered indicator.
+ */
+export declare const EmptyStateIndicator: React.FC<EmptyStateIndicatorProps>;
+/**
+ * The heading, a Bulma `Title` at the level `as` sets, `h2` by default, and at the EmptyState's size.
+ *
+ * @function
+ * @param {EmptyStateTitleProps} props - Props for EmptyState.Title.
+ * @returns {JSX.Element} The rendered heading.
+ */
+export declare const EmptyStateTitle: React.FC<EmptyStateTitleProps>;
+/**
+ * A sentence or two under the title, in the color of the text around it.
+ *
+ * @function
+ * @param {EmptyStateDescriptionProps} props - Props for EmptyState.Description.
+ * @returns {JSX.Element} The rendered description.
+ */
+export declare const EmptyStateDescription: React.FC<EmptyStateDescriptionProps>;
+/**
+ * A row of buttons, centered under the text or at the start of the line beside the indicator.
+ *
+ * @function
+ * @param {EmptyStateActionsProps} props - Props for EmptyState.Actions.
+ * @returns {JSX.Element} The rendered row of buttons.
+ */
+export declare const EmptyStateActions: React.FC<EmptyStateActionsProps>;
+export declare const EmptyState: React.ForwardRefExoticComponent<EmptyStateProps & React.RefAttributes<HTMLDivElement>> & {
+    Indicator: React.FC<EmptyStateIndicatorProps>;
+    Title: React.FC<EmptyStateTitleProps>;
+    Description: React.FC<ParagraphProps>;
+    Actions: React.FC<EmptyStateActionsProps>;
+};
+export default EmptyState;

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

@@ -8,7 +8,7 @@ export type ButtonsSize = (typeof validButtonsSizes)[number];
 /**
  * Props for the Buttons component.
  */
-interface ButtonsProps extends React.HTMLAttributes<HTMLDivElement>, Omit<BulmaClassesProps, 'size'> {
+export interface ButtonsProps extends React.HTMLAttributes<HTMLDivElement>, Omit<BulmaClassesProps, 'size'> {
     /** Additional CSS classes to apply. */
     className?: string;
     /** Text color helper for the button group. */

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

@@ -16,9 +16,20 @@ export type SubTitleElement = (typeof validSubTitleElements)[number];
 export interface SubTitleProps extends Omit<React.HTMLAttributes<HTMLHeadingElement | HTMLParagraphElement>, 'color'>, Omit<BulmaClassesProps, 'backgroundColor' | 'color'> {
     /** Additional CSS classes to apply. */
     className?: string;
-    /** Size of the subtitle (Bulma sizes `1`-`6`, as a string or number). */
+    /**
+     * Size of the subtitle (Bulma sizes `1`-`6`, as a string or number). It
+     * also picks the heading level: unless `as` is `p`, `size="5"` renders an
+     * `<h5>`, whatever `as` says. For a heading whose level and size differ,
+     * set the level with `as` and the size with the `textSize` helper.
+     */
     size?: SubTitleSize;
-    /** HTML element to render as (h1-h6 or p). */
+    /**
+     * HTML element to render as (`h1`-`h6` or `p`). With neither `as` nor
+     * `size` set it's an `<h1>`, so a subtitle that isn't a heading of its own
+     * takes `as="p"`. A `size` overrides `as` unless it's `p`, so
+     * `as="h3" size="5"` renders an `<h5>`. To keep the level `as` sets, size
+     * the subtitle with the `textSize` helper instead.
+     */
     as?: SubTitleElement;
     /** Applies the `has-skeleton` class to part of the content. */
     hasSkeleton?: boolean;

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

@@ -16,11 +16,20 @@ export type TitleElement = (typeof validTitleElements)[number];
 export interface TitleProps extends Omit<React.HTMLAttributes<HTMLHeadingElement | HTMLParagraphElement>, 'color'>, Omit<BulmaClassesProps, 'backgroundColor' | 'color'> {
     /** Additional CSS classes to apply. */
     className?: string;
-    /** Size of the title (Bulma sizes `1`-`6`, as a string or number). */
+    /**
+     * Size of the title (Bulma sizes `1`-`6`, as a string or number). It also
+     * picks the heading level: unless `as` is `p`, `size="4"` renders an
+     * `<h4>`, whatever `as` says. For a heading whose level and size differ,
+     * set the level with `as` and the size with the `textSize` helper.
+     */
     size?: TitleSize;
     /** Adds margin below the title. */
     isSpaced?: boolean;
-    /** HTML element to render as (h1-h6 or p). */
+    /**
+     * HTML element to render as (`h1`-`h6` or `p`). A `size` overrides it
+     * unless it's `p`, so `as="h2" size="4"` renders an `<h4>`. To keep the
+     * level `as` sets, size the title with the `textSize` helper instead.
+     */
     as?: TitleElement;
     /** Applies the `has-skeleton` class to part of the content. */
     hasSkeleton?: boolean;

package/dist/types/index.d.ts

@@ -6,6 +6,7 @@ export * from './components/Badge.js';
 export * from './components/Breadcrumb.js';
 export * from './components/Card.js';
 export * from './components/Dropdown.js';
+export * from './components/EmptyState.js';
 export * from './components/Menu.js';
 export * from './components/Message.js';
 export * from './components/Modal.js';

package/dist/types-cjs/components/EmptyState.d.ts

@@ -0,0 +1,149 @@
+import React from 'react';
+import { BulmaClassesProps, validColors } from '../helpers/useBulmaClasses.js';
+import { ButtonsProps } from '../elements/Buttons.js';
+import { ParagraphProps } from '../elements/Paragraph.js';
+import { TitleProps } from '../elements/Title.js';
+declare const validEmptyStateColors: readonly ["primary", "link", "info", "success", "warning", "danger"];
+/** The Bulma colors the indicator takes. */
+export type EmptyStateColor = (typeof validEmptyStateColors)[number];
+declare const validEmptyStateHeadings: readonly ["h1", "h2", "h3", "h4", "h5", "h6"];
+/** A title's heading level. It's always a heading, so there's no `p`. */
+export type EmptyStateHeading = (typeof validEmptyStateHeadings)[number];
+/**
+ * Props for the EmptyState component. The helper props, the other attributes
+ * and the `ref` land on the root `<div>`. The native `title` attribute isn't
+ * one of them, since `title` here is the heading.
+ *
+ * @extraProp {React.Ref<HTMLDivElement>} [ref] - Ref forwarded to the root `<div>`.
+ */
+export interface EmptyStateProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'color' | 'title'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /** Additional CSS classes to apply. */
+    className?: string;
+    /**
+     * The picture in the indicator's circle. A string is an `Icon` name, drawn
+     * from the icon library `ConfigProvider` sets. Anything else (an `<Icon>`
+     * with its own `variant` or `library`, an SVG, an `<img>`) renders as it is.
+     * It's decorative and hidden from assistive tech, so the title says what
+     * it means.
+     */
+    icon?: React.ReactNode;
+    /**
+     * The heading, rendered as `EmptyState.Title`. It's always a real heading,
+     * at the level `titleAs` sets.
+     */
+    title?: React.ReactNode;
+    /**
+     * The heading level for `title`: the level under the heading of the list
+     * it stands in for, such as `h3` for a list under an `h2`. Only this sets
+     * the level, and the size comes from `size`.
+     */
+    titleAs?: EmptyStateHeading;
+    /** A sentence or two under the title, rendered as `EmptyState.Description`. */
+    description?: React.ReactNode;
+    /**
+     * Rendered as written, after whatever `icon`, `title` and `description`
+     * render. One button can go straight in, and it sits centered under the
+     * text. Group two or more in `EmptyState.Actions`, or they stack. Without
+     * the props, write the parts here in the order they're shown:
+     * `EmptyState.Indicator`, `.Title`, `.Description`, then the actions.
+     */
+    children?: React.ReactNode;
+    /**
+     * The indicator's color. It colors the circle and its icon, not the text.
+     * Without it the circle is neutral, since an empty list isn't a status.
+     */
+    color?: EmptyStateColor;
+    /**
+     * `light` is a soft tint of `color` behind the icon in the color. `filled`
+     * is the color itself, with the icon in its invert.
+     */
+    variant?: 'light' | 'filled';
+    /** Sizes the indicator, the title, the description and the spacing together. */
+    size?: 'small' | 'normal' | 'medium' | 'large';
+    /**
+     * `center` stacks everything in a centered column. `left` puts the
+     * indicator beside the text, at the start of the line, so on the right in
+     * a right-to-left page, and keeps the block at least as tall as the circle
+     * whatever block padding is in effect. Without an indicator, it only puts
+     * the text at the start of the line. In `left`, the padding at the start
+     * of the line is what makes room for the indicator, so pad it with `py`
+     * rather than `p` or `px`.
+     */
+    align?: 'center' | 'left';
+    /** Text color helper. */
+    textColor?: (typeof validColors)[number] | 'inherit' | 'current';
+    /** Background color helper. */
+    bgColor?: (typeof validColors)[number] | 'inherit' | 'current';
+}
+/** Props for EmptyState.Indicator, the circle the picture sits in. */
+export interface EmptyStateIndicatorProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'color'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /** Additional CSS classes to apply. */
+    className?: string;
+    /**
+     * The picture: an `Icon`, an SVG or an `<img>`. The indicator is hidden
+     * from assistive tech, an `Icon` with an `ariaLabel` included, so anything
+     * it means goes in the title or the description.
+     */
+    children?: React.ReactNode;
+    /** Text color helper. */
+    textColor?: (typeof validColors)[number] | 'inherit' | 'current';
+    /** Background color helper. */
+    bgColor?: (typeof validColors)[number] | 'inherit' | 'current';
+}
+/**
+ * Props for EmptyState.Title. It renders `Title` with `as` and never `size`,
+ * so the level is `as` alone and the size comes from the EmptyState.
+ */
+export interface EmptyStateTitleProps extends Omit<TitleProps, 'as' | 'size' | 'isSpaced'> {
+    /**
+     * The heading level: the level under the heading of the list the empty
+     * state stands in for.
+     */
+    as?: EmptyStateHeading;
+}
+/** Props for EmptyState.Description, a `<p>` under the title. */
+export type EmptyStateDescriptionProps = ParagraphProps;
+/**
+ * Props for EmptyState.Actions, the row of buttons. It renders `Buttons`,
+ * and the EmptyState aligns it, so `isCentered` and `isRight` are left out.
+ */
+export type EmptyStateActionsProps = Omit<ButtonsProps, 'isCentered' | 'isRight'>;
+/**
+ * The circle the picture sits in, hidden from assistive tech whatever is in it.
+ *
+ * @function
+ * @param {EmptyStateIndicatorProps} props - Props for EmptyState.Indicator.
+ * @returns {JSX.Element} The rendered indicator.
+ */
+export declare const EmptyStateIndicator: React.FC<EmptyStateIndicatorProps>;
+/**
+ * The heading, a Bulma `Title` at the level `as` sets, `h2` by default, and at the EmptyState's size.
+ *
+ * @function
+ * @param {EmptyStateTitleProps} props - Props for EmptyState.Title.
+ * @returns {JSX.Element} The rendered heading.
+ */
+export declare const EmptyStateTitle: React.FC<EmptyStateTitleProps>;
+/**
+ * A sentence or two under the title, in the color of the text around it.
+ *
+ * @function
+ * @param {EmptyStateDescriptionProps} props - Props for EmptyState.Description.
+ * @returns {JSX.Element} The rendered description.
+ */
+export declare const EmptyStateDescription: React.FC<EmptyStateDescriptionProps>;
+/**
+ * A row of buttons, centered under the text or at the start of the line beside the indicator.
+ *
+ * @function
+ * @param {EmptyStateActionsProps} props - Props for EmptyState.Actions.
+ * @returns {JSX.Element} The rendered row of buttons.
+ */
+export declare const EmptyStateActions: React.FC<EmptyStateActionsProps>;
+export declare const EmptyState: React.ForwardRefExoticComponent<EmptyStateProps & React.RefAttributes<HTMLDivElement>> & {
+    Indicator: React.FC<EmptyStateIndicatorProps>;
+    Title: React.FC<EmptyStateTitleProps>;
+    Description: React.FC<ParagraphProps>;
+    Actions: React.FC<EmptyStateActionsProps>;
+};
+export default EmptyState;

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

@@ -8,7 +8,7 @@ export type ButtonsSize = (typeof validButtonsSizes)[number];
 /**
  * Props for the Buttons component.
  */
-interface ButtonsProps extends React.HTMLAttributes<HTMLDivElement>, Omit<BulmaClassesProps, 'size'> {
+export interface ButtonsProps extends React.HTMLAttributes<HTMLDivElement>, Omit<BulmaClassesProps, 'size'> {
     /** Additional CSS classes to apply. */
     className?: string;
     /** Text color helper for the button group. */

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

@@ -16,9 +16,20 @@ export type SubTitleElement = (typeof validSubTitleElements)[number];
 export interface SubTitleProps extends Omit<React.HTMLAttributes<HTMLHeadingElement | HTMLParagraphElement>, 'color'>, Omit<BulmaClassesProps, 'backgroundColor' | 'color'> {
     /** Additional CSS classes to apply. */
     className?: string;
-    /** Size of the subtitle (Bulma sizes `1`-`6`, as a string or number). */
+    /**
+     * Size of the subtitle (Bulma sizes `1`-`6`, as a string or number). It
+     * also picks the heading level: unless `as` is `p`, `size="5"` renders an
+     * `<h5>`, whatever `as` says. For a heading whose level and size differ,
+     * set the level with `as` and the size with the `textSize` helper.
+     */
     size?: SubTitleSize;
-    /** HTML element to render as (h1-h6 or p). */
+    /**
+     * HTML element to render as (`h1`-`h6` or `p`). With neither `as` nor
+     * `size` set it's an `<h1>`, so a subtitle that isn't a heading of its own
+     * takes `as="p"`. A `size` overrides `as` unless it's `p`, so
+     * `as="h3" size="5"` renders an `<h5>`. To keep the level `as` sets, size
+     * the subtitle with the `textSize` helper instead.
+     */
     as?: SubTitleElement;
     /** Applies the `has-skeleton` class to part of the content. */
     hasSkeleton?: boolean;

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

@@ -16,11 +16,20 @@ export type TitleElement = (typeof validTitleElements)[number];
 export interface TitleProps extends Omit<React.HTMLAttributes<HTMLHeadingElement | HTMLParagraphElement>, 'color'>, Omit<BulmaClassesProps, 'backgroundColor' | 'color'> {
     /** Additional CSS classes to apply. */
     className?: string;
-    /** Size of the title (Bulma sizes `1`-`6`, as a string or number). */
+    /**
+     * Size of the title (Bulma sizes `1`-`6`, as a string or number). It also
+     * picks the heading level: unless `as` is `p`, `size="4"` renders an
+     * `<h4>`, whatever `as` says. For a heading whose level and size differ,
+     * set the level with `as` and the size with the `textSize` helper.
+     */
     size?: TitleSize;
     /** Adds margin below the title. */
     isSpaced?: boolean;
-    /** HTML element to render as (h1-h6 or p). */
+    /**
+     * HTML element to render as (`h1`-`h6` or `p`). A `size` overrides it
+     * unless it's `p`, so `as="h2" size="4"` renders an `<h4>`. To keep the
+     * level `as` sets, size the title with the `textSize` helper instead.
+     */
     as?: TitleElement;
     /** Applies the `has-skeleton` class to part of the content. */
     hasSkeleton?: boolean;

package/dist/types-cjs/index.d.ts

@@ -6,6 +6,7 @@ export * from './components/Badge.js';
 export * from './components/Breadcrumb.js';
 export * from './components/Card.js';
 export * from './components/Dropdown.js';
+export * from './components/EmptyState.js';
 export * from './components/Menu.js';
 export * from './components/Message.js';
 export * from './components/Modal.js';