@allxsmith/bestax-bulma 5.31.0 → 5.32.0

package/dist/index.esm.js

@@ -14,6 +14,7 @@ export { Navbar, NavbarBrand, NavbarBurger, NavbarDivider, NavbarDropdown, Navba
 export { Pagination, PaginationEllipsis, PaginationLink, PaginationList, PaginationNext, PaginationPrevious } from './esm/components/Pagination.js';
 export { Panel, PanelBlock, PanelButtonBlock, PanelCheckboxBlock, PanelHeading, PanelIcon, PanelInputBlock, PanelTabs } from './esm/components/Panel.js';
 export { Tab, TabContentItem, TabItem, TabList, Tabs, TabsContent } from './esm/components/Tabs.js';
+export { SegmentedControl } from './esm/components/SegmentedControl.js';
 export { Loading } from './esm/components/Loading.js';
 export { Collapse } from './esm/components/Collapse.js';
 export { Collapses } from './esm/components/Collapses.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/SegmentedControl.d.ts

@@ -0,0 +1,116 @@
+import React from 'react';
+import { type ButtonOwnProps } from '../elements/Button.js';
+import { BulmaClassesProps } from '../helpers/useBulmaClasses.js';
+/**
+ * The fills the checked segment takes: `Button`'s colors, minus `text` and
+ * `ghost`, which don't fill, and `white`, `light`, `dark` and `black`, which in
+ * one theme or the other fill about as light or dark as an unchecked segment
+ * already is. The same set `ToggleButton` takes.
+ */
+export type SegmentedControlColor = 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';
+/**
+ * Props for the SegmentedControl component. The helper props, the other `<div>`
+ * attributes and the `ref` all land on the row.
+ *
+ * @extraProp {string} [aria-label] - Names the group for a screen reader, such as "Text alignment". A radio group needs a name, so pass this or `aria-labelledby`, and a development build warns when it has neither.
+ * @extraProp {string} [aria-labelledby] - The id of a visible heading or label that names the group, in place of `aria-label`.
+ * @extraProp {React.Ref<HTMLDivElement>} [ref] - Ref forwarded to the row's `<div>`.
+ */
+export interface SegmentedControlProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue' | 'color' | 'role'>, Omit<BulmaClassesProps, 'color' | 'colorShade' | 'backgroundColor' | 'backgroundColorShade'> {
+    /**
+     * The checked segment's `value`, when you hold the state. Setting it makes
+     * the group controlled: picking a segment only calls `onChange`, and nothing
+     * changes until you pass the new value. `null` checks nothing, with the
+     * tab stop `defaultValue` describes for that. Pick this or `defaultValue`
+     * for the group's lifetime.
+     */
+    value?: string | null;
+    /**
+     * The segment checked to begin with, when the group holds its own state.
+     * Leave it out and nothing is checked until someone picks one, and Tab
+     * lands on the first enabled segment meanwhile. That fallback takes hold
+     * once the row has rendered in the browser: server markup with nothing
+     * checked has no tab stop until then, while a checked segment is the stop
+     * from the server markup on.
+     */
+    defaultValue?: string;
+    /**
+     * Called with the newly checked segment's `value`, whether or not `value`
+     * is set. The arrow keys, Home and End check the segment they move to, so
+     * each of those calls it too: the check follows focus, as in a native radio
+     * group. Pressing the checked segment again doesn't call it, since a
+     * segmented control can't be cleared: one stays checked once one is.
+     */
+    onChange?: (value: string) => void;
+    /**
+     * The checked segment's fill. The others are plain buttons, so the fill is
+     * the difference people see. Takes the same colors as `ToggleButton`, for
+     * the same reason: `white`, `light`, `dark` and `black` fill about as light
+     * or dark as a plain button already is in one theme or the other.
+     */
+    color?: SegmentedControlColor;
+    /** Size of every segment, through Bulma's `are-<size>` on the row. */
+    size?: 'small' | 'medium' | 'large';
+    /**
+     * Joins the segments into one row with no gap between them, Bulma's
+     * `has-addons`. Set it to `false` for separate buttons.
+     */
+    hasAddons?: boolean;
+    /** Centers the row. */
+    isCentered?: boolean;
+    /** Aligns the row to the right. */
+    isRight?: boolean;
+    /** Additional CSS classes to apply. */
+    className?: string;
+    /** The `SegmentedControl.Segment`s, each with a `value` of its own. */
+    children?: React.ReactNode;
+}
+/**
+ * Props for SegmentedControl.Segment. The helper props, the other button
+ * attributes and the `ref` all land on the `<button>`.
+ *
+ * Some of `Button`'s props are left out on purpose. `as`, `type`, `role` and
+ * `tabIndex`, since a segment is always a `<button type="button" role="radio">`
+ * and the group decides which segment Tab reaches. `color`, which the group
+ * sets for the checked segment, and the props that change the fill
+ * (`isActive`, `isLight`, `isOutlined`, `isInverted`, `textColor`, `bgColor`
+ * and their shades), since each would color it whether checked or not. `size`
+ * and the width and shape props, which the row sets for every segment. And
+ * `isStatic` and `isLoading`, a segment you couldn't pick.
+ *
+ * @extraProp {React.Ref<HTMLButtonElement>} [ref] - Ref forwarded to the `<button>`.
+ */
+export interface SegmentedControlSegmentProps extends Omit<ButtonOwnProps, 'color' | 'size' | 'isActive' | 'isStatic' | 'isLoading' | 'isLight' | 'isOutlined' | 'isInverted' | 'isRounded' | 'isFullwidth' | 'isFullWidth' | 'textColor' | 'bgColor' | 'colorShade' | 'backgroundColorShade'>, Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, keyof ButtonOwnProps | 'type' | 'value' | 'role' | 'tabIndex' | 'aria-checked' | 'aria-pressed'> {
+    /**
+     * **Required.** What `onChange` reports when this segment is checked, and
+     * what the group's `value` and `defaultValue` name it by. Unique within the
+     * group.
+     */
+    value: string;
+    /**
+     * The label. An icon on its own needs an `aria-label`, so a screen reader
+     * has something to say.
+     */
+    children?: React.ReactNode;
+    /**
+     * Disables the segment, the same as `disabled`: it can't be clicked, the
+     * arrow keys, Home and End skip it, and it never holds the row's tab stop.
+     * A checked one keeps its fill under Bulma's disabled look.
+     */
+    isDisabled?: boolean;
+    /**
+     * Not accepted: `aria-checked` follows the group's value. Declared because
+     * JSX lets a hyphenated attribute through when the props don't name it.
+     * @internal
+     */
+    'aria-checked'?: never;
+    /**
+     * Not accepted: a segment is a radio, which says checked, not pressed.
+     * @internal
+     */
+    'aria-pressed'?: never;
+}
+export declare const SegmentedControl: React.ForwardRefExoticComponent<SegmentedControlProps & React.RefAttributes<HTMLDivElement>> & {
+    Segment: React.ForwardRefExoticComponent<SegmentedControlSegmentProps & React.RefAttributes<HTMLButtonElement>>;
+};
+export default SegmentedControl;

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

@@ -78,7 +78,8 @@ export interface ToggleButtonProps extends Omit<ButtonOwnProps, 'color' | 'isAct
  * carries no form value: a setting saved with a form is a `Checkbox` or a
  * `Switch`. A set of toggles that each turn on and off on their own goes in
  * `Buttons hasAddons` with `role="group"` and an `aria-label`. A set where only
- * one can be on is a radio group rather than a row of these: use `Radios`.
+ * one can be on is a radio group rather than a row of these: use
+ * `SegmentedControl`, or `Radios` for a choice that's sent with a form.
  *
  * @function
  * @param {ToggleButtonProps} props - Props for the ToggleButton component.

package/dist/types/index.d.ts

@@ -13,6 +13,7 @@ export * from './components/Navbar.js';
 export * from './components/Pagination.js';
 export * from './components/Panel.js';
 export * from './components/Tabs.js';
+export * from './components/SegmentedControl.js';
 export * from './components/Loading.js';
 export * from './components/Collapse.js';
 export * from './components/Collapses.js';

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

@@ -0,0 +1,116 @@
+import React from 'react';
+import { type ButtonOwnProps } from '../elements/Button.js';
+import { BulmaClassesProps } from '../helpers/useBulmaClasses.js';
+/**
+ * The fills the checked segment takes: `Button`'s colors, minus `text` and
+ * `ghost`, which don't fill, and `white`, `light`, `dark` and `black`, which in
+ * one theme or the other fill about as light or dark as an unchecked segment
+ * already is. The same set `ToggleButton` takes.
+ */
+export type SegmentedControlColor = 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';
+/**
+ * Props for the SegmentedControl component. The helper props, the other `<div>`
+ * attributes and the `ref` all land on the row.
+ *
+ * @extraProp {string} [aria-label] - Names the group for a screen reader, such as "Text alignment". A radio group needs a name, so pass this or `aria-labelledby`, and a development build warns when it has neither.
+ * @extraProp {string} [aria-labelledby] - The id of a visible heading or label that names the group, in place of `aria-label`.
+ * @extraProp {React.Ref<HTMLDivElement>} [ref] - Ref forwarded to the row's `<div>`.
+ */
+export interface SegmentedControlProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue' | 'color' | 'role'>, Omit<BulmaClassesProps, 'color' | 'colorShade' | 'backgroundColor' | 'backgroundColorShade'> {
+    /**
+     * The checked segment's `value`, when you hold the state. Setting it makes
+     * the group controlled: picking a segment only calls `onChange`, and nothing
+     * changes until you pass the new value. `null` checks nothing, with the
+     * tab stop `defaultValue` describes for that. Pick this or `defaultValue`
+     * for the group's lifetime.
+     */
+    value?: string | null;
+    /**
+     * The segment checked to begin with, when the group holds its own state.
+     * Leave it out and nothing is checked until someone picks one, and Tab
+     * lands on the first enabled segment meanwhile. That fallback takes hold
+     * once the row has rendered in the browser: server markup with nothing
+     * checked has no tab stop until then, while a checked segment is the stop
+     * from the server markup on.
+     */
+    defaultValue?: string;
+    /**
+     * Called with the newly checked segment's `value`, whether or not `value`
+     * is set. The arrow keys, Home and End check the segment they move to, so
+     * each of those calls it too: the check follows focus, as in a native radio
+     * group. Pressing the checked segment again doesn't call it, since a
+     * segmented control can't be cleared: one stays checked once one is.
+     */
+    onChange?: (value: string) => void;
+    /**
+     * The checked segment's fill. The others are plain buttons, so the fill is
+     * the difference people see. Takes the same colors as `ToggleButton`, for
+     * the same reason: `white`, `light`, `dark` and `black` fill about as light
+     * or dark as a plain button already is in one theme or the other.
+     */
+    color?: SegmentedControlColor;
+    /** Size of every segment, through Bulma's `are-<size>` on the row. */
+    size?: 'small' | 'medium' | 'large';
+    /**
+     * Joins the segments into one row with no gap between them, Bulma's
+     * `has-addons`. Set it to `false` for separate buttons.
+     */
+    hasAddons?: boolean;
+    /** Centers the row. */
+    isCentered?: boolean;
+    /** Aligns the row to the right. */
+    isRight?: boolean;
+    /** Additional CSS classes to apply. */
+    className?: string;
+    /** The `SegmentedControl.Segment`s, each with a `value` of its own. */
+    children?: React.ReactNode;
+}
+/**
+ * Props for SegmentedControl.Segment. The helper props, the other button
+ * attributes and the `ref` all land on the `<button>`.
+ *
+ * Some of `Button`'s props are left out on purpose. `as`, `type`, `role` and
+ * `tabIndex`, since a segment is always a `<button type="button" role="radio">`
+ * and the group decides which segment Tab reaches. `color`, which the group
+ * sets for the checked segment, and the props that change the fill
+ * (`isActive`, `isLight`, `isOutlined`, `isInverted`, `textColor`, `bgColor`
+ * and their shades), since each would color it whether checked or not. `size`
+ * and the width and shape props, which the row sets for every segment. And
+ * `isStatic` and `isLoading`, a segment you couldn't pick.
+ *
+ * @extraProp {React.Ref<HTMLButtonElement>} [ref] - Ref forwarded to the `<button>`.
+ */
+export interface SegmentedControlSegmentProps extends Omit<ButtonOwnProps, 'color' | 'size' | 'isActive' | 'isStatic' | 'isLoading' | 'isLight' | 'isOutlined' | 'isInverted' | 'isRounded' | 'isFullwidth' | 'isFullWidth' | 'textColor' | 'bgColor' | 'colorShade' | 'backgroundColorShade'>, Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, keyof ButtonOwnProps | 'type' | 'value' | 'role' | 'tabIndex' | 'aria-checked' | 'aria-pressed'> {
+    /**
+     * **Required.** What `onChange` reports when this segment is checked, and
+     * what the group's `value` and `defaultValue` name it by. Unique within the
+     * group.
+     */
+    value: string;
+    /**
+     * The label. An icon on its own needs an `aria-label`, so a screen reader
+     * has something to say.
+     */
+    children?: React.ReactNode;
+    /**
+     * Disables the segment, the same as `disabled`: it can't be clicked, the
+     * arrow keys, Home and End skip it, and it never holds the row's tab stop.
+     * A checked one keeps its fill under Bulma's disabled look.
+     */
+    isDisabled?: boolean;
+    /**
+     * Not accepted: `aria-checked` follows the group's value. Declared because
+     * JSX lets a hyphenated attribute through when the props don't name it.
+     * @internal
+     */
+    'aria-checked'?: never;
+    /**
+     * Not accepted: a segment is a radio, which says checked, not pressed.
+     * @internal
+     */
+    'aria-pressed'?: never;
+}
+export declare const SegmentedControl: React.ForwardRefExoticComponent<SegmentedControlProps & React.RefAttributes<HTMLDivElement>> & {
+    Segment: React.ForwardRefExoticComponent<SegmentedControlSegmentProps & React.RefAttributes<HTMLButtonElement>>;
+};
+export default SegmentedControl;

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

@@ -78,7 +78,8 @@ export interface ToggleButtonProps extends Omit<ButtonOwnProps, 'color' | 'isAct
  * carries no form value: a setting saved with a form is a `Checkbox` or a
  * `Switch`. A set of toggles that each turn on and off on their own goes in
  * `Buttons hasAddons` with `role="group"` and an `aria-label`. A set where only
- * one can be on is a radio group rather than a row of these: use `Radios`.
+ * one can be on is a radio group rather than a row of these: use
+ * `SegmentedControl`, or `Radios` for a choice that's sent with a form.
  *
  * @function
  * @param {ToggleButtonProps} props - Props for the ToggleButton component.

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

@@ -13,6 +13,7 @@ export * from './components/Navbar.js';
 export * from './components/Pagination.js';
 export * from './components/Panel.js';
 export * from './components/Tabs.js';
+export * from './components/SegmentedControl.js';
 export * from './components/Loading.js';
 export * from './components/Collapse.js';
 export * from './components/Collapses.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allxsmith/bestax-bulma",
-  "version": "5.31.0",
+  "version": "5.32.0",
   "description": "A fully-typed React component library for the Bulma CSS framework. Build modern UIs quickly with reusable, accessible, and customizable Bulma-based React components.",
   "main": "dist/index.cjs",
   "module": "dist/index.esm.js",