@allxsmith/bestax-bulma 5.32.0 → 5.33.1

package/dist/index.esm.js

@@ -43,6 +43,7 @@ export { Figure } from './esm/elements/Figure.js';
 export { Icon } from './esm/elements/Icon.js';
 export { IconText } from './esm/elements/IconText.js';
 export { Image } from './esm/elements/Image.js';
+export { Kbd, KbdGroup } from './esm/elements/Kbd.js';
 export { Link } from './esm/elements/Link.js';
 export { ListItem } from './esm/elements/ListItem.js';
 export { Loader } from './esm/elements/Loader.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/Kbd.d.ts

@@ -0,0 +1,100 @@
+import React from 'react';
+import { BulmaClassesProps, validColors } from '../helpers/useBulmaClasses.js';
+/**
+ * Props for the Kbd component. The helper props, the other attributes and
+ * the `ref` land on the `<kbd>`.
+ *
+ * @extraProp {React.Ref<HTMLElement>} [ref] - Ref forwarded to the `<kbd>`.
+ */
+export interface KbdProps extends Omit<React.HTMLAttributes<HTMLElement>, 'color'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /** Additional CSS classes to apply. */
+    className?: string;
+    /**
+     * The key as it's printed on the keyboard: a word (`Ctrl`, `Esc`), a
+     * letter, or a symbol (`⌘`).
+     */
+    children?: React.ReactNode;
+    /**
+     * What a screen reader says in place of a symbol, in your app's language:
+     * `label="Command"` on `⌘`. The symbol is hidden from assistive tech with
+     * `aria-hidden`, and the label is read in its place, from text that's
+     * visually hidden. Use it for a glyph that isn't a word, such as `⌘`, `⌥`,
+     * `⇧`, `⌃` or `⏎`, and leave it off a key written as a word. Copying the
+     * key copies the label along with the glyph. Don't reach for `aria-label`
+     * instead: ARIA in HTML prohibits naming a `<kbd>`, so nothing obliges a
+     * screen reader to read it.
+     */
+    label?: string;
+    /**
+     * Text color helper. The key's edge and fill are mixed from its text
+     * color, so they follow it.
+     */
+    textColor?: (typeof validColors)[number] | 'inherit' | 'current';
+    /**
+     * Background color helper. It replaces the key's faint fill, and the text
+     * still follows the text around it, which turns light in dark mode, so pair
+     * it with a `textColor` that reads on that color in both schemes, such as
+     * `textColor="black"` on `bgColor="warning"`.
+     */
+    bgColor?: (typeof validColors)[number] | 'inherit' | 'current';
+}
+/**
+ * Props for Kbd.Group, keys pressed together or one after another. The
+ * group renders the outer `<kbd>` of a combination, and the helper props,
+ * the other attributes and the `ref` land on it.
+ *
+ * @extraProp {React.Ref<HTMLElement>} [ref] - Ref forwarded to the outer `<kbd>`.
+ */
+export interface KbdGroupProps extends Omit<React.HTMLAttributes<HTMLElement>, 'color'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /** Additional CSS classes to apply. */
+    className?: string;
+    /**
+     * The keys, a `Kbd` each, in the order they're pressed. The group renders
+     * the outer `<kbd>` around them, so it doesn't go inside a `Kbd` of its
+     * own, and it puts the separator between them, so don't type one: a `+`
+     * of your own doubles up. A `null` or `false` child, or an empty Fragment,
+     * gets no separator, and the keys in a Fragment are separated like the
+     * rest. A component that renders nothing still gets one, since the group
+     * can't see what a child renders, so write a conditional key inline
+     * (`{isMac && <Kbd label="Command">⌘</Kbd>}`), not in a component of its
+     * own.
+     */
+    children?: React.ReactNode;
+    /**
+     * What goes between the keys, shown and read aloud, with a space either
+     * side. Use `'then'` for a sequence pressed one key after another. It's a
+     * string because a screen reader has to read it.
+     */
+    separator?: string;
+    /** Text color helper. The keys and separators inside follow it. */
+    textColor?: (typeof validColors)[number] | 'inherit' | 'current';
+}
+/**
+ * Keys pressed together or one after another, in the outer `<kbd>` HTML gives a combination, with the separator between each pair as text.
+ *
+ * It doesn't wrap in the middle and isn't drawn as a key itself. It sets no
+ * font size, so the keys in it are the size of a key on its own.
+ *
+ * @function
+ * @param {KbdGroupProps} props - Props for Kbd.Group.
+ * @param {React.Ref<HTMLElement>} ref - Forwarded ref to the outer `<kbd>`.
+ * @returns {JSX.Element} The rendered combination.
+ *
+ * @example
+ * <Kbd.Group>
+ *   <Kbd>Ctrl</Kbd>
+ *   <Kbd>Shift</Kbd>
+ *   <Kbd>P</Kbd>
+ * </Kbd.Group>
+ *
+ * @example
+ * <Kbd.Group separator="then">
+ *   <Kbd>G</Kbd>
+ *   <Kbd>I</Kbd>
+ * </Kbd.Group>
+ */
+export declare const KbdGroup: React.ForwardRefExoticComponent<KbdGroupProps & React.RefAttributes<HTMLElement>>;
+export declare const Kbd: React.ForwardRefExoticComponent<KbdProps & React.RefAttributes<HTMLElement>> & {
+    Group: React.ForwardRefExoticComponent<KbdGroupProps & React.RefAttributes<HTMLElement>>;
+};
+export default Kbd;

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

@@ -88,11 +88,26 @@ export interface AutocompleteProps extends Omit<React.HTMLAttributes<HTMLDivElem
     onInfiniteScroll?: () => void;
     /** Custom render for items. */
     itemTemplate?: (item: AutocompleteItem | string) => React.ReactNode;
-    /** Custom header in dropdown. */
+    /** Custom header at the top of the dropdown. It sits above the list of options rather than in it, so assistive technology doesn't count it as one. */
     header?: React.ReactNode;
-    /** Custom footer in dropdown. */
+    /** Custom footer at the bottom of the dropdown. It sits below the list of options rather than in it, so assistive technology doesn't count it as one. */
     footer?: React.ReactNode;
-    /** Content to show when no results. */
+    /**
+     * A message the dropdown shows in place of the options when nothing
+     * matches. Keep it to text: `Tab` closes the list, so a keyboard user
+     * can't reach a link or button in it. It sits beside the list of options
+     * rather than in it, so the input's `aria-expanded` stays false while it
+     * shows. When the user's typing leaves nothing that matches, a polite
+     * status region announces its text: once each time the matches run out.
+     * The text is read when they first run out, and isn't read again as it
+     * changes while they stay out, so a message that names the query is heard
+     * for that first query only. Keep it static.
+     * Opening the list without typing, or emptying the field, announces
+     * nothing. While `loading`, or a `Control` with `isLoading` around the
+     * Autocomplete, is on, it waits, and it's announced once loading ends
+     * with nothing matching. Without `empty`, the dropdown closes when nothing
+     * matches and nothing is announced.
+     */
     empty?: React.ReactNode;
 }
 /**

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

@@ -0,0 +1,16 @@
+import React from 'react';
+/**
+ * A component's children as a flat list, with each Fragment opened up
+ * (recursively) so the items inside one count one by one rather than as the
+ * Fragment. `Children.toArray` already drops `null`, `undefined` and
+ * booleans and flattens arrays, but it keeps a Fragment whole, so an empty
+ * one would still count as an item and two items in one would count as one.
+ *
+ * `Children.toArray` keys restart at ".0" inside each Fragment, so the items
+ * in one are re-keyed with the Fragment's own key as a prefix. Otherwise an
+ * item in a Fragment and a sibling outside it could share a key.
+ *
+ * Text and numbers pass through as they are, so a caller that wants only
+ * elements filters with `React.isValidElement`.
+ */
+export declare function flattenChildren(children: React.ReactNode, keyPrefix?: string): React.ReactNode[];

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

@@ -43,10 +43,10 @@ export interface StatusRegionProps<Item extends {
     describe: (item: Item) => string | null;
 }
 /**
- * A visually hidden, polite `status` live region that a programmatic
- * container announces its items through. The container renders it from the
- * moment it mounts, whether or not it has anything to show, so the region is
- * already in the page when an announcement is written into it.
+ * A visually hidden, polite `status` live region that a container announces
+ * its items through. The container renders it from the moment it mounts,
+ * whether or not it has anything to show, so the region is already in the
+ * page when an announcement is written into it.
  *
  * The announcements are this component's own state, so writing and clearing
  * them re-renders the region and leaves the container's items alone. Each one

package/dist/types/index.d.ts

@@ -42,6 +42,7 @@ export * from './elements/Figure.js';
 export * from './elements/Icon.js';
 export * from './elements/IconText.js';
 export * from './elements/Image.js';
+export * from './elements/Kbd.js';
 export * from './elements/Link.js';
 export * from './elements/ListItem.js';
 export * from './elements/Loader.js';

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

@@ -0,0 +1,100 @@
+import React from 'react';
+import { BulmaClassesProps, validColors } from '../helpers/useBulmaClasses.js';
+/**
+ * Props for the Kbd component. The helper props, the other attributes and
+ * the `ref` land on the `<kbd>`.
+ *
+ * @extraProp {React.Ref<HTMLElement>} [ref] - Ref forwarded to the `<kbd>`.
+ */
+export interface KbdProps extends Omit<React.HTMLAttributes<HTMLElement>, 'color'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /** Additional CSS classes to apply. */
+    className?: string;
+    /**
+     * The key as it's printed on the keyboard: a word (`Ctrl`, `Esc`), a
+     * letter, or a symbol (`⌘`).
+     */
+    children?: React.ReactNode;
+    /**
+     * What a screen reader says in place of a symbol, in your app's language:
+     * `label="Command"` on `⌘`. The symbol is hidden from assistive tech with
+     * `aria-hidden`, and the label is read in its place, from text that's
+     * visually hidden. Use it for a glyph that isn't a word, such as `⌘`, `⌥`,
+     * `⇧`, `⌃` or `⏎`, and leave it off a key written as a word. Copying the
+     * key copies the label along with the glyph. Don't reach for `aria-label`
+     * instead: ARIA in HTML prohibits naming a `<kbd>`, so nothing obliges a
+     * screen reader to read it.
+     */
+    label?: string;
+    /**
+     * Text color helper. The key's edge and fill are mixed from its text
+     * color, so they follow it.
+     */
+    textColor?: (typeof validColors)[number] | 'inherit' | 'current';
+    /**
+     * Background color helper. It replaces the key's faint fill, and the text
+     * still follows the text around it, which turns light in dark mode, so pair
+     * it with a `textColor` that reads on that color in both schemes, such as
+     * `textColor="black"` on `bgColor="warning"`.
+     */
+    bgColor?: (typeof validColors)[number] | 'inherit' | 'current';
+}
+/**
+ * Props for Kbd.Group, keys pressed together or one after another. The
+ * group renders the outer `<kbd>` of a combination, and the helper props,
+ * the other attributes and the `ref` land on it.
+ *
+ * @extraProp {React.Ref<HTMLElement>} [ref] - Ref forwarded to the outer `<kbd>`.
+ */
+export interface KbdGroupProps extends Omit<React.HTMLAttributes<HTMLElement>, 'color'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /** Additional CSS classes to apply. */
+    className?: string;
+    /**
+     * The keys, a `Kbd` each, in the order they're pressed. The group renders
+     * the outer `<kbd>` around them, so it doesn't go inside a `Kbd` of its
+     * own, and it puts the separator between them, so don't type one: a `+`
+     * of your own doubles up. A `null` or `false` child, or an empty Fragment,
+     * gets no separator, and the keys in a Fragment are separated like the
+     * rest. A component that renders nothing still gets one, since the group
+     * can't see what a child renders, so write a conditional key inline
+     * (`{isMac && <Kbd label="Command">⌘</Kbd>}`), not in a component of its
+     * own.
+     */
+    children?: React.ReactNode;
+    /**
+     * What goes between the keys, shown and read aloud, with a space either
+     * side. Use `'then'` for a sequence pressed one key after another. It's a
+     * string because a screen reader has to read it.
+     */
+    separator?: string;
+    /** Text color helper. The keys and separators inside follow it. */
+    textColor?: (typeof validColors)[number] | 'inherit' | 'current';
+}
+/**
+ * Keys pressed together or one after another, in the outer `<kbd>` HTML gives a combination, with the separator between each pair as text.
+ *
+ * It doesn't wrap in the middle and isn't drawn as a key itself. It sets no
+ * font size, so the keys in it are the size of a key on its own.
+ *
+ * @function
+ * @param {KbdGroupProps} props - Props for Kbd.Group.
+ * @param {React.Ref<HTMLElement>} ref - Forwarded ref to the outer `<kbd>`.
+ * @returns {JSX.Element} The rendered combination.
+ *
+ * @example
+ * <Kbd.Group>
+ *   <Kbd>Ctrl</Kbd>
+ *   <Kbd>Shift</Kbd>
+ *   <Kbd>P</Kbd>
+ * </Kbd.Group>
+ *
+ * @example
+ * <Kbd.Group separator="then">
+ *   <Kbd>G</Kbd>
+ *   <Kbd>I</Kbd>
+ * </Kbd.Group>
+ */
+export declare const KbdGroup: React.ForwardRefExoticComponent<KbdGroupProps & React.RefAttributes<HTMLElement>>;
+export declare const Kbd: React.ForwardRefExoticComponent<KbdProps & React.RefAttributes<HTMLElement>> & {
+    Group: React.ForwardRefExoticComponent<KbdGroupProps & React.RefAttributes<HTMLElement>>;
+};
+export default Kbd;

package/dist/types-cjs/form/Autocomplete.d.ts

@@ -88,11 +88,26 @@ export interface AutocompleteProps extends Omit<React.HTMLAttributes<HTMLDivElem
     onInfiniteScroll?: () => void;
     /** Custom render for items. */
     itemTemplate?: (item: AutocompleteItem | string) => React.ReactNode;
-    /** Custom header in dropdown. */
+    /** Custom header at the top of the dropdown. It sits above the list of options rather than in it, so assistive technology doesn't count it as one. */
     header?: React.ReactNode;
-    /** Custom footer in dropdown. */
+    /** Custom footer at the bottom of the dropdown. It sits below the list of options rather than in it, so assistive technology doesn't count it as one. */
     footer?: React.ReactNode;
-    /** Content to show when no results. */
+    /**
+     * A message the dropdown shows in place of the options when nothing
+     * matches. Keep it to text: `Tab` closes the list, so a keyboard user
+     * can't reach a link or button in it. It sits beside the list of options
+     * rather than in it, so the input's `aria-expanded` stays false while it
+     * shows. When the user's typing leaves nothing that matches, a polite
+     * status region announces its text: once each time the matches run out.
+     * The text is read when they first run out, and isn't read again as it
+     * changes while they stay out, so a message that names the query is heard
+     * for that first query only. Keep it static.
+     * Opening the list without typing, or emptying the field, announces
+     * nothing. While `loading`, or a `Control` with `isLoading` around the
+     * Autocomplete, is on, it waits, and it's announced once loading ends
+     * with nothing matching. Without `empty`, the dropdown closes when nothing
+     * matches and nothing is announced.
+     */
     empty?: React.ReactNode;
 }
 /**

package/dist/types-cjs/helpers/flattenChildren.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+/**
+ * A component's children as a flat list, with each Fragment opened up
+ * (recursively) so the items inside one count one by one rather than as the
+ * Fragment. `Children.toArray` already drops `null`, `undefined` and
+ * booleans and flattens arrays, but it keeps a Fragment whole, so an empty
+ * one would still count as an item and two items in one would count as one.
+ *
+ * `Children.toArray` keys restart at ".0" inside each Fragment, so the items
+ * in one are re-keyed with the Fragment's own key as a prefix. Otherwise an
+ * item in a Fragment and a sibling outside it could share a key.
+ *
+ * Text and numbers pass through as they are, so a caller that wants only
+ * elements filters with `React.isValidElement`.
+ */
+export declare function flattenChildren(children: React.ReactNode, keyPrefix?: string): React.ReactNode[];

package/dist/types-cjs/helpers/statusRegion.d.ts

@@ -43,10 +43,10 @@ export interface StatusRegionProps<Item extends {
     describe: (item: Item) => string | null;
 }
 /**
- * A visually hidden, polite `status` live region that a programmatic
- * container announces its items through. The container renders it from the
- * moment it mounts, whether or not it has anything to show, so the region is
- * already in the page when an announcement is written into it.
+ * A visually hidden, polite `status` live region that a container announces
+ * its items through. The container renders it from the moment it mounts,
+ * whether or not it has anything to show, so the region is already in the
+ * page when an announcement is written into it.
  *
  * The announcements are this component's own state, so writing and clearing
  * them re-renders the region and leaves the container's items alone. Each one

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

@@ -42,6 +42,7 @@ export * from './elements/Figure.js';
 export * from './elements/Icon.js';
 export * from './elements/IconText.js';
 export * from './elements/Image.js';
+export * from './elements/Kbd.js';
 export * from './elements/Link.js';
 export * from './elements/ListItem.js';
 export * from './elements/Loader.js';