@allxsmith/bestax-bulma 5.35.0 → 5.36.0

package/dist/index.esm.js

@@ -24,6 +24,7 @@ export { Popover, PopoverBody, PopoverClose, PopoverFooter, PopoverHeader } from
 export { HoverCard } from './esm/components/HoverCard.js';
 export { ContextMenu } from './esm/components/ContextMenu.js';
 export { Step, Steps } from './esm/components/Steps.js';
+export { Timeline, TimelineItem } from './esm/components/Timeline.js';
 export { Sidebar } from './esm/components/Sidebar.js';
 export { Toast, ToastContainer, toast } from './esm/components/Toast.js';
 export { Dialog, DialogContainer, dialog } from './esm/components/Dialog.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/Timeline.d.ts

@@ -0,0 +1,130 @@
+import React from 'react';
+import { BulmaClassesProps, validColors } from '../helpers/useBulmaClasses.js';
+declare const validTimelineColors: readonly ["primary", "link", "info", "success", "warning", "danger"];
+/** The Bulma colors a marker takes. */
+export type TimelineColor = (typeof validTimelineColors)[number];
+declare const validTimelineTitleElements: readonly ["h2", "h3", "h4", "h5", "h6", "p"];
+/** What each item's title renders as: a heading level, or `p` for a plain line. */
+export type TimelineTitleElement = (typeof validTimelineTitleElements)[number];
+/** Where the rail goes. */
+export type TimelineAlign = 'start' | 'end' | 'alternate';
+/**
+ * Props for the Timeline component. The helper props, the other attributes
+ * and the `ref` land on the `<ol>`.
+ *
+ * @extraProp {React.Ref<HTMLOListElement>} [ref] - Ref forwarded to the `<ol>`.
+ */
+export interface TimelineProps extends Omit<React.OlHTMLAttributes<HTMLOListElement>, 'color' | 'role'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /** Additional CSS classes to apply. */
+    className?: string;
+    /**
+     * `Timeline.Item`s, in the order they're read: newest first or oldest
+     * first for a record, oldest first with `active` or `pending`.
+     */
+    children?: React.ReactNode;
+    /**
+     * Marks progress. The item at this index, counting the children from 0, is
+     * current; the ones before it are completed and the ones after it are
+     * upcoming. Leave it out for a record, where nothing is marked. `-1` marks
+     * every item upcoming, and an index past the last marks them all completed.
+     * A fraction counts as the item it has reached, so `2.5` marks the third
+     * item current. Each child counts as one item, with Fragments and arrays opened up, so
+     * render one item per child. A component of your own around a
+     * `Timeline.Item` still gets its state, but one that renders nothing still
+     * counts.
+     */
+    active?: number;
+    /**
+     * What's under way, as a last item after the children: its title, read
+     * with `pendingLabel`. Write it as words that say so ("Out for delivery").
+     */
+    pending?: React.ReactNode;
+    /**
+     * `start`: the rail at the start of the line. `end`: at the end, with the
+     * text against it. `alternate`: down the middle, the items taking turns and
+     * each time across the rail; below Bulma's tablet breakpoint it's `start`.
+     */
+    align?: TimelineAlign;
+    /**
+     * What every item's title renders as: a heading at the level under the
+     * heading the timeline sits beneath, or `p` for a busy feed.
+     */
+    titleAs?: TimelineTitleElement;
+    /**
+     * The markers' color, and the color of progress with `active`. Neutral
+     * without it, and Bulma's `link` for progress. The markers are hidden from
+     * assistive tech, so say what a color means in the words too.
+     */
+    color?: TimelineColor;
+    /** Read after a completed item's title, visually hidden. In your app's language. */
+    completedLabel?: string;
+    /** Read after an upcoming item's title, visually hidden. In your app's language. */
+    upcomingLabel?: string;
+    /** Read after the pending item's title, visually hidden. In your app's language. */
+    pendingLabel?: string;
+    /** Text color helper. */
+    textColor?: (typeof validColors)[number] | 'inherit' | 'current';
+    /** Background color helper. */
+    bgColor?: (typeof validColors)[number] | 'inherit' | 'current';
+}
+/**
+ * Props for Timeline.Item, one event. The helper props, the other attributes
+ * and the `ref` land on its `<li>`. The native `title` attribute isn't one of
+ * them, since `title` here is the event's title.
+ *
+ * @extraProp {React.Ref<HTMLLIElement>} [ref] - Ref forwarded to the `<li>`.
+ */
+export interface TimelineItemProps extends Omit<React.LiHTMLAttributes<HTMLLIElement>, 'color' | 'title'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /** Additional CSS classes to apply. */
+    className?: string;
+    /** What happened, in a line. It renders as the root's `titleAs`. */
+    title?: React.ReactNode;
+    /**
+     * When it happened, as the reader sees it: "14 October 2026", "2 hours
+     * ago". Put the whole date in the words, since screen readers mostly read
+     * the text.
+     */
+    time?: React.ReactNode;
+    /**
+     * The same moment for machines, as HTML's `datetime` takes it:
+     * "2026-10-14", "2026-10-14T08:12", "2026-10". With it, `time` renders in
+     * a `<time>`. Keep it the same moment as `time`, since some readers speak it.
+     */
+    dateTime?: string;
+    /**
+     * A picture in the marker. A string is an `Icon` name, drawn from the icon
+     * library `ConfigProvider` sets, and anything else renders as it is.
+     * Without it, the marker is a dot. It's hidden from assistive tech, so
+     * what it means goes in the title.
+     */
+    icon?: React.ReactNode;
+    /** This item's marker color, over the root's. Say what it means in the words too. */
+    color?: TimelineColor;
+    /** Anything else about the event, under the title and the time, as written. */
+    children?: React.ReactNode;
+    /** Text color helper. */
+    textColor?: (typeof validColors)[number] | 'inherit' | 'current';
+    /** Background color helper. */
+    bgColor?: (typeof validColors)[number] | 'inherit' | 'current';
+}
+/**
+ * One event: a marker on the rail, then its title, its time and anything else about it.
+ *
+ * Outside a `Timeline` it's a record item with an `h2` title, though the
+ * styles are registered on `.timeline`, so the rail and the marker need one.
+ *
+ * @function
+ * @param {TimelineItemProps} props - Props for Timeline.Item.
+ * @param {React.Ref<HTMLLIElement>} ref - Forwarded ref to the `<li>`.
+ * @returns {JSX.Element} The rendered event.
+ *
+ * @example
+ * <Timeline.Item title="Shipped" time="14 October 2026" dateTime="2026-10-14">
+ *   Left the warehouse in Leeds.
+ * </Timeline.Item>
+ */
+export declare const TimelineItem: React.ForwardRefExoticComponent<TimelineItemProps & React.RefAttributes<HTMLLIElement>>;
+export declare const Timeline: React.ForwardRefExoticComponent<TimelineProps & React.RefAttributes<HTMLOListElement>> & {
+    Item: React.ForwardRefExoticComponent<TimelineItemProps & React.RefAttributes<HTMLLIElement>>;
+};
+export default Timeline;

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

@@ -29,7 +29,12 @@ interface IconBaseProps extends React.HTMLAttributes<HTMLSpanElement>, BulmaClas
     className?: string;
     /** Text color helper. */
     textColor?: (typeof validColors)[number] | 'inherit' | 'current';
-    /** Bulma color modifier for the icon. */
+    /**
+     * Text color alias: renders `has-text-<color>`, exactly like `textColor`.
+     * Not a filled variant (no `.icon.is-<color>` CSS exists). Prefer
+     * `textColor`, which takes precedence when both are set; use `bgColor` for
+     * a colored surface.
+     */
     color?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';
     /** Background color helper. */
     bgColor?: (typeof validColors)[number] | 'inherit' | 'current';

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

@@ -26,7 +26,7 @@ type IconLibrary = 'fa' | 'mdi' | 'ion' | 'material-icons' | 'material-symbols';
  * @extraProp {React.Ref<HTMLInputElement>} [ref] - Ref forwarded to the input element.
  */
 export interface TaginputProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'>, Omit<BulmaClassesProps, 'color'>, FormFieldProps {
-    /** Field label. Automatically associated with the text input via `htmlFor` — uses your `id` when provided, otherwise a generated one. Not wired when the tag limit is reached (the input is not rendered). Dropped inside an outer `Field`, whose own label associates instead when that `Field` generates a target id (not `grouped`/`hasAddons`, no explicit `labelProps.htmlFor`) and you set no `id` here; it then replaces the `aria-label="Add tag"` fallback too. With `data`, the label naming the input also names the open suggestion list, through `aria-labelledby`, when it has an id: this label always does, and an outer `Field`'s does unless you wired it by hand without an `id` in its `labelProps`. Otherwise the list is named "Suggestions". */
+    /** Field label. Automatically associated with the text input via `htmlFor` — uses your `id` when provided, otherwise a generated one. Dropped inside an outer `Field`, whose own label associates instead when that `Field` generates a target id (not `grouped`/`hasAddons`, no explicit `labelProps.htmlFor`) and you set no `id` here; it then replaces the `aria-label="Add tag"` fallback too. With `data`, the label naming the input also names the open suggestion list, through `aria-labelledby`, when it has an id: this label always does, and an outer `Field`'s does unless you wired it by hand without an `id` in its `labelProps`. Otherwise the list is named "Suggestions". */
     label?: React.ReactNode;
     /** Props for the label element. An explicit `htmlFor` here overrides the automatic association (no id is generated then). With `data`, while the label names the input, the suggestion list's `aria-labelledby` points at it, through an `id` here when you give one and a generated one otherwise. */
     labelProps?: React.LabelHTMLAttributes<HTMLLabelElement> & {
@@ -64,9 +64,11 @@ export interface TaginputProps extends Omit<React.HTMLAttributes<HTMLDivElement>
     /** Attach tags visually. */
     attached?: boolean;
     /**
-     * Maximum number of tags allowed. At the limit the text input isn't
-     * rendered, and neither is the suggestion list, so the field takes no more
-     * tags until one is removed.
+     * Maximum number of tags allowed. At the limit the text input stays but
+     * turns read-only, so focus stays put and the label still names it. It
+     * takes no more tags and the suggestion list stays closed. Backspace (with
+     * `removeOnKeys`) or a tag's remove button makes room again. While the
+     * counter shows, it describes the input.
      */
     maxTags?: number;
     /** Maximum length of input. */
@@ -81,7 +83,12 @@ export interface TaginputProps extends Omit<React.HTMLAttributes<HTMLDivElement>
     ellipsis?: boolean;
     /** Shows a counter of the number of tags. */
     hasCounter?: boolean;
-    /** Characters that split pasted text into tags. */
+    /**
+     * Characters that split pasted text into tags. Each part goes through the
+     * same checks as a typed tag, against the tags before it, the paste's own
+     * included, and adding stops at `maxTags`. `onChange` fires once for the
+     * whole paste, and `onAdd` once for each tag it adds.
+     */
     onPasteSeparators?: string[];
     /** Validation function called before adding a tag. */
     beforeAdding?: (tag: string) => boolean;

package/dist/types/index.d.ts

@@ -23,6 +23,7 @@ export * from './components/Popover.js';
 export * from './components/HoverCard.js';
 export * from './components/ContextMenu.js';
 export * from './components/Steps.js';
+export * from './components/Timeline.js';
 export * from './components/Sidebar.js';
 export * from './components/Toast.js';
 export * from './components/Dialog.js';

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

@@ -0,0 +1,130 @@
+import React from 'react';
+import { BulmaClassesProps, validColors } from '../helpers/useBulmaClasses.js';
+declare const validTimelineColors: readonly ["primary", "link", "info", "success", "warning", "danger"];
+/** The Bulma colors a marker takes. */
+export type TimelineColor = (typeof validTimelineColors)[number];
+declare const validTimelineTitleElements: readonly ["h2", "h3", "h4", "h5", "h6", "p"];
+/** What each item's title renders as: a heading level, or `p` for a plain line. */
+export type TimelineTitleElement = (typeof validTimelineTitleElements)[number];
+/** Where the rail goes. */
+export type TimelineAlign = 'start' | 'end' | 'alternate';
+/**
+ * Props for the Timeline component. The helper props, the other attributes
+ * and the `ref` land on the `<ol>`.
+ *
+ * @extraProp {React.Ref<HTMLOListElement>} [ref] - Ref forwarded to the `<ol>`.
+ */
+export interface TimelineProps extends Omit<React.OlHTMLAttributes<HTMLOListElement>, 'color' | 'role'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /** Additional CSS classes to apply. */
+    className?: string;
+    /**
+     * `Timeline.Item`s, in the order they're read: newest first or oldest
+     * first for a record, oldest first with `active` or `pending`.
+     */
+    children?: React.ReactNode;
+    /**
+     * Marks progress. The item at this index, counting the children from 0, is
+     * current; the ones before it are completed and the ones after it are
+     * upcoming. Leave it out for a record, where nothing is marked. `-1` marks
+     * every item upcoming, and an index past the last marks them all completed.
+     * A fraction counts as the item it has reached, so `2.5` marks the third
+     * item current. Each child counts as one item, with Fragments and arrays opened up, so
+     * render one item per child. A component of your own around a
+     * `Timeline.Item` still gets its state, but one that renders nothing still
+     * counts.
+     */
+    active?: number;
+    /**
+     * What's under way, as a last item after the children: its title, read
+     * with `pendingLabel`. Write it as words that say so ("Out for delivery").
+     */
+    pending?: React.ReactNode;
+    /**
+     * `start`: the rail at the start of the line. `end`: at the end, with the
+     * text against it. `alternate`: down the middle, the items taking turns and
+     * each time across the rail; below Bulma's tablet breakpoint it's `start`.
+     */
+    align?: TimelineAlign;
+    /**
+     * What every item's title renders as: a heading at the level under the
+     * heading the timeline sits beneath, or `p` for a busy feed.
+     */
+    titleAs?: TimelineTitleElement;
+    /**
+     * The markers' color, and the color of progress with `active`. Neutral
+     * without it, and Bulma's `link` for progress. The markers are hidden from
+     * assistive tech, so say what a color means in the words too.
+     */
+    color?: TimelineColor;
+    /** Read after a completed item's title, visually hidden. In your app's language. */
+    completedLabel?: string;
+    /** Read after an upcoming item's title, visually hidden. In your app's language. */
+    upcomingLabel?: string;
+    /** Read after the pending item's title, visually hidden. In your app's language. */
+    pendingLabel?: string;
+    /** Text color helper. */
+    textColor?: (typeof validColors)[number] | 'inherit' | 'current';
+    /** Background color helper. */
+    bgColor?: (typeof validColors)[number] | 'inherit' | 'current';
+}
+/**
+ * Props for Timeline.Item, one event. The helper props, the other attributes
+ * and the `ref` land on its `<li>`. The native `title` attribute isn't one of
+ * them, since `title` here is the event's title.
+ *
+ * @extraProp {React.Ref<HTMLLIElement>} [ref] - Ref forwarded to the `<li>`.
+ */
+export interface TimelineItemProps extends Omit<React.LiHTMLAttributes<HTMLLIElement>, 'color' | 'title'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /** Additional CSS classes to apply. */
+    className?: string;
+    /** What happened, in a line. It renders as the root's `titleAs`. */
+    title?: React.ReactNode;
+    /**
+     * When it happened, as the reader sees it: "14 October 2026", "2 hours
+     * ago". Put the whole date in the words, since screen readers mostly read
+     * the text.
+     */
+    time?: React.ReactNode;
+    /**
+     * The same moment for machines, as HTML's `datetime` takes it:
+     * "2026-10-14", "2026-10-14T08:12", "2026-10". With it, `time` renders in
+     * a `<time>`. Keep it the same moment as `time`, since some readers speak it.
+     */
+    dateTime?: string;
+    /**
+     * A picture in the marker. A string is an `Icon` name, drawn from the icon
+     * library `ConfigProvider` sets, and anything else renders as it is.
+     * Without it, the marker is a dot. It's hidden from assistive tech, so
+     * what it means goes in the title.
+     */
+    icon?: React.ReactNode;
+    /** This item's marker color, over the root's. Say what it means in the words too. */
+    color?: TimelineColor;
+    /** Anything else about the event, under the title and the time, as written. */
+    children?: React.ReactNode;
+    /** Text color helper. */
+    textColor?: (typeof validColors)[number] | 'inherit' | 'current';
+    /** Background color helper. */
+    bgColor?: (typeof validColors)[number] | 'inherit' | 'current';
+}
+/**
+ * One event: a marker on the rail, then its title, its time and anything else about it.
+ *
+ * Outside a `Timeline` it's a record item with an `h2` title, though the
+ * styles are registered on `.timeline`, so the rail and the marker need one.
+ *
+ * @function
+ * @param {TimelineItemProps} props - Props for Timeline.Item.
+ * @param {React.Ref<HTMLLIElement>} ref - Forwarded ref to the `<li>`.
+ * @returns {JSX.Element} The rendered event.
+ *
+ * @example
+ * <Timeline.Item title="Shipped" time="14 October 2026" dateTime="2026-10-14">
+ *   Left the warehouse in Leeds.
+ * </Timeline.Item>
+ */
+export declare const TimelineItem: React.ForwardRefExoticComponent<TimelineItemProps & React.RefAttributes<HTMLLIElement>>;
+export declare const Timeline: React.ForwardRefExoticComponent<TimelineProps & React.RefAttributes<HTMLOListElement>> & {
+    Item: React.ForwardRefExoticComponent<TimelineItemProps & React.RefAttributes<HTMLLIElement>>;
+};
+export default Timeline;

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

@@ -29,7 +29,12 @@ interface IconBaseProps extends React.HTMLAttributes<HTMLSpanElement>, BulmaClas
     className?: string;
     /** Text color helper. */
     textColor?: (typeof validColors)[number] | 'inherit' | 'current';
-    /** Bulma color modifier for the icon. */
+    /**
+     * Text color alias: renders `has-text-<color>`, exactly like `textColor`.
+     * Not a filled variant (no `.icon.is-<color>` CSS exists). Prefer
+     * `textColor`, which takes precedence when both are set; use `bgColor` for
+     * a colored surface.
+     */
     color?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';
     /** Background color helper. */
     bgColor?: (typeof validColors)[number] | 'inherit' | 'current';

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

@@ -26,7 +26,7 @@ type IconLibrary = 'fa' | 'mdi' | 'ion' | 'material-icons' | 'material-symbols';
  * @extraProp {React.Ref<HTMLInputElement>} [ref] - Ref forwarded to the input element.
  */
 export interface TaginputProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'>, Omit<BulmaClassesProps, 'color'>, FormFieldProps {
-    /** Field label. Automatically associated with the text input via `htmlFor` — uses your `id` when provided, otherwise a generated one. Not wired when the tag limit is reached (the input is not rendered). Dropped inside an outer `Field`, whose own label associates instead when that `Field` generates a target id (not `grouped`/`hasAddons`, no explicit `labelProps.htmlFor`) and you set no `id` here; it then replaces the `aria-label="Add tag"` fallback too. With `data`, the label naming the input also names the open suggestion list, through `aria-labelledby`, when it has an id: this label always does, and an outer `Field`'s does unless you wired it by hand without an `id` in its `labelProps`. Otherwise the list is named "Suggestions". */
+    /** Field label. Automatically associated with the text input via `htmlFor` — uses your `id` when provided, otherwise a generated one. Dropped inside an outer `Field`, whose own label associates instead when that `Field` generates a target id (not `grouped`/`hasAddons`, no explicit `labelProps.htmlFor`) and you set no `id` here; it then replaces the `aria-label="Add tag"` fallback too. With `data`, the label naming the input also names the open suggestion list, through `aria-labelledby`, when it has an id: this label always does, and an outer `Field`'s does unless you wired it by hand without an `id` in its `labelProps`. Otherwise the list is named "Suggestions". */
     label?: React.ReactNode;
     /** Props for the label element. An explicit `htmlFor` here overrides the automatic association (no id is generated then). With `data`, while the label names the input, the suggestion list's `aria-labelledby` points at it, through an `id` here when you give one and a generated one otherwise. */
     labelProps?: React.LabelHTMLAttributes<HTMLLabelElement> & {
@@ -64,9 +64,11 @@ export interface TaginputProps extends Omit<React.HTMLAttributes<HTMLDivElement>
     /** Attach tags visually. */
     attached?: boolean;
     /**
-     * Maximum number of tags allowed. At the limit the text input isn't
-     * rendered, and neither is the suggestion list, so the field takes no more
-     * tags until one is removed.
+     * Maximum number of tags allowed. At the limit the text input stays but
+     * turns read-only, so focus stays put and the label still names it. It
+     * takes no more tags and the suggestion list stays closed. Backspace (with
+     * `removeOnKeys`) or a tag's remove button makes room again. While the
+     * counter shows, it describes the input.
      */
     maxTags?: number;
     /** Maximum length of input. */
@@ -81,7 +83,12 @@ export interface TaginputProps extends Omit<React.HTMLAttributes<HTMLDivElement>
     ellipsis?: boolean;
     /** Shows a counter of the number of tags. */
     hasCounter?: boolean;
-    /** Characters that split pasted text into tags. */
+    /**
+     * Characters that split pasted text into tags. Each part goes through the
+     * same checks as a typed tag, against the tags before it, the paste's own
+     * included, and adding stops at `maxTags`. `onChange` fires once for the
+     * whole paste, and `onAdd` once for each tag it adds.
+     */
     onPasteSeparators?: string[];
     /** Validation function called before adding a tag. */
     beforeAdding?: (tag: string) => boolean;

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

@@ -23,6 +23,7 @@ export * from './components/Popover.js';
 export * from './components/HoverCard.js';
 export * from './components/ContextMenu.js';
 export * from './components/Steps.js';
+export * from './components/Timeline.js';
 export * from './components/Sidebar.js';
 export * from './components/Toast.js';
 export * from './components/Dialog.js';