@allxsmith/bestax-bulma 5.32.0 → 5.33.0

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/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/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/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/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';