@allxsmith/bestax-bulma 5.52.0 → 5.53.0

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

@@ -49,7 +49,15 @@ export interface DateTimeInputBaseProps extends Omit<React.InputHTMLAttributes<H
      * keeps what the format leaves out, such as seconds.
      */
     parse?: (s: string) => Date | null;
-    /** BCP-47 locale tag. */
+    /**
+     * BCP-47 locale tag for day/month names and Intl formatting. Unset, it is
+     * the `locale` of a `LocaleProvider` around the picker, and with neither,
+     * `Intl` uses the runtime's own locale. On a server render that is the
+     * server's, so an `inline` calendar rendered there names its days in the
+     * server's language and the browser's own render names them in the
+     * browser's: give it a locale, here or through a `LocaleProvider`, where
+     * the two can differ.
+     */
     locale?: string;
     /** Render the panel inline (no popover). */
     inline?: boolean;
@@ -96,9 +104,23 @@ export interface DateTimeInputBaseProps extends Omit<React.InputHTMLAttributes<H
     shouldDisableDate?: (d: Date) => boolean;
     /** Convenience array of disabled dates, matched by calendar day; also rejected by manual typing. */
     unselectableDates?: Date[];
-    /** Day the calendar week starts on. */
+    /**
+     * Day the week starts on (0 = Sunday). Unset inside a `LocaleProvider`,
+     * it is the first day of the week in the picker's locale, its own `locale`
+     * or else the provider's, such as Monday for `"de"`. Elsewhere, with no
+     * locale from either, or with seven `dayNames` of your own, it is Sunday:
+     * set it with `dayNames` to start the week on another day.
+     * @defaultValue 0
+     */
     firstDayOfWeek?: DayOfWeek;
-    /** Override the 7 day-name labels. */
+    /**
+     * Override the 7 day-name labels (in calendar order, post-rotation). They
+     * are shown exactly as given, from the first column, so they have to start
+     * on the day the week does. With them, an unset `firstDayOfWeek` stays
+     * Sunday even inside a `LocaleProvider`, so names written Sunday first keep
+     * matching their columns; to start on the locale's day, set
+     * `firstDayOfWeek` too and list the names from that day.
+     */
     dayNames?: string[];
     /** Override the 12 month-name labels. */
     monthNames?: string[];

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

@@ -0,0 +1,86 @@
+import React from 'react';
+import { BulmaClassesProps, validColors } from '../helpers/useBulmaClasses.js';
+import type { FormFieldProps } from './fieldProps.js';
+/** The looks a Fieldset comes in. */
+export type FieldsetVariant = 'default' | 'filled' | 'unstyled';
+/**
+ * Props for the Fieldset component. The helper props, the other attributes
+ * and the `ref` land on its `<fieldset>`.
+ *
+ * @extraProp {React.Ref<HTMLFieldSetElement>} [ref] - Ref forwarded to the `<fieldset>`, whose `elements` lists the controls inside.
+ * @extraProp {string} [aria-describedby] - Ids of more text that describes the group. The `message`'s id is added after them.
+ * @extraProp {string} [name] - The fieldset's name in its form's `elements`. Nothing is submitted under it.
+ */
+export interface FieldsetProps extends Omit<React.FieldsetHTMLAttributes<HTMLFieldSetElement>, 'color'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /**
+     * The group's name, shown in a `<legend>`, which names the fieldset with no
+     * ids to wire. The `default` and `filled` variants draw it on the border,
+     * and `unstyled` above the content. Controls you put in it, such as a
+     * `Checkbox` that turns the section on, stay enabled when the Fieldset is
+     * disabled, as the browser leaves them.
+     */
+    legend?: React.ReactNode;
+    /** Props for the `<legend>`, such as an `id` or a `className`. */
+    legendProps?: React.HTMLAttributes<HTMLLegendElement>;
+    /**
+     * The look: `default` draws a border round the group, `filled` adds a
+     * tinted background, and `unstyled` draws no box at all, which suits a
+     * Fieldset that's there to name or disable a group.
+     */
+    variant?: FieldsetVariant;
+    /**
+     * Disables every control inside. The browser disables the native ones and
+     * leaves them out of the form's data, and each bestax input with a
+     * `disabled` prop takes this as that prop's default, which also stops
+     * widgets the browser doesn't reach, such as `Rate`'s stars and the time
+     * wheels, and gives them their disabled look. An input's own `disabled`
+     * still wins when you set it, though the browser keeps its native parts
+     * disabled whatever it says. Links and `LinkButton`s stay operable, as in
+     * plain HTML.
+     */
+    disabled?: boolean;
+    /**
+     * Help text under the group. It describes the fieldset through
+     * `aria-describedby`, alongside any ids you pass there. Nothing passes it
+     * to the inputs, so each still shows its own errors.
+     */
+    message?: React.ReactNode;
+    /** Bulma color for the message. */
+    messageColor?: FormFieldProps['messageColor'];
+    /** Text color helper, for the text in the group. The legend keeps its own color. */
+    textColor?: (typeof validColors)[number] | 'inherit' | 'current';
+    /** Background color helper. */
+    bgColor?: (typeof validColors)[number] | 'inherit' | 'current';
+    /** Additional CSS classes. */
+    className?: string;
+    /** The group's content, such as `Field`s and inputs. */
+    children?: React.ReactNode;
+}
+/**
+ * The `Fieldset` component groups a section of a form in a native
+ * `<fieldset>`, named by its `legend`, which a `disabled` switches off as a
+ * whole.
+ *
+ * It starts its own Field scope: inside it, nothing reads as inside a
+ * `Field` or `Control`, so the convenience inputs render their own `Field`,
+ * and a labeled `Field` around the Fieldset names nothing in it.
+ *
+ * @function
+ * @param {FieldsetProps} props - Props for the Fieldset component.
+ * @returns {JSX.Element} The rendered fieldset.
+ *
+ * @example
+ * <Fieldset legend="Shipping address" message="We only ship within the EU.">
+ *   <Input label="Street" name="street" />
+ *   <Input label="City" name="city" />
+ * </Fieldset>
+ *
+ * @example
+ * // A form that's saving
+ * <Fieldset disabled={saving} variant="unstyled">
+ *   <Input label="Name" name="name" />
+ *   <Rate label="Rating" name="rating" />
+ * </Fieldset>
+ */
+export declare const Fieldset: React.ForwardRefExoticComponent<FieldsetProps & React.RefAttributes<HTMLFieldSetElement>>;
+export default Fieldset;

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

@@ -14,6 +14,18 @@ export declare const useInsideControl: () => boolean;
 export declare const FieldProvider: React.Provider<boolean>;
 /** Provider for Control context — used internally by Control component. */
 export declare const ControlProvider: React.Provider<boolean>;
+/**
+ * An input's `disabled`: its own prop when the caller set one, otherwise
+ * whether a disabled `Fieldset` holds it. A `<fieldset disabled>` disables the
+ * native controls inside on its own, and this carries the same state to what
+ * the browser doesn't reach, such as Rate's stars, the time wheels, and the
+ * `is-disabled` classes. The content of a Fieldset's legend reads the state
+ * from outside that Fieldset, as the browser leaves the first legend's
+ * controls enabled. Internal; not part of the public API.
+ */
+export declare const useFieldsetDisabled: (disabled: boolean | undefined) => boolean;
+/** Provider for a Fieldset's disabled state, used internally by Fieldset. */
+export declare const FieldsetDisabledProvider: React.Provider<boolean>;
 /** The wrapper props that change what its own `Field` renders. */
 interface FieldShapingProps {
     /** Rendered as the `Field`'s label. */

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

@@ -42,7 +42,11 @@ export interface TimeInputBaseProps extends Omit<React.InputHTMLAttributes<HTMLI
      * keeps what the format leaves out, such as seconds and the date.
      */
     parse?: (s: string) => Date | null;
-    /** BCP-47 locale tag for Intl formatting. */
+    /**
+     * BCP-47 locale tag for Intl formatting. Unset, it is the `locale` of a
+     * `LocaleProvider` around the picker, and with neither, `Intl` uses the
+     * runtime's own locale.
+     */
     locale?: string;
     /** Render the spinner inline (no popover). */
     inline?: boolean;

package/dist/types-cjs/form/_pickerInternals/PickerPopover.d.ts

@@ -1,4 +1,5 @@
 import React from 'react';
+import { type PortalLocale } from '../../helpers/LocaleProvider.js';
 import { PickerPosition } from './pickerTypes.js';
 export interface PickerPopoverProps {
     isOpen: boolean;
@@ -29,6 +30,11 @@ export interface PickerPopoverProps {
      * nothing matches, or the match can't take focus, the first tab stop does.
      */
     initialFocusSelector?: string;
+    /**
+     * The `dir` and `lang` the panel carries when it portals, in place of a
+     * `LocaleProvider`'s: the picker's own, from `usePickerLocaleScope`.
+     */
+    localeScope?: PortalLocale;
 }
 export declare const PickerPopover: React.FC<PickerPopoverProps>;
 export default PickerPopover;

package/dist/types-cjs/form/_pickerInternals/useLocaleDefaults.d.ts

@@ -0,0 +1,49 @@
+import { type PortalLocale } from '../../helpers/LocaleProvider.js';
+import type { DayOfWeek } from './pickerTypes.js';
+/**
+ * A picker's locale: its own `locale`, else the one a `LocaleProvider` around
+ * it sets, else `undefined`, which leaves `Intl` to use the runtime's.
+ */
+export declare function usePickerLocale(own: string | undefined): string | undefined;
+/** Where a picker's own language and direction go, inside a `LocaleProvider`. */
+export interface PickerLocaleScope {
+    /**
+     * The `lang` and `dir` for the picker's root, so what renders inside it,
+     * an inline calendar or a popover in place, follows them. Empty unless the
+     * picker has a `locale` of its own.
+     */
+    rootAttrs: {
+        lang?: string;
+        dir?: string;
+    };
+    /** What its portaled panel carries; unset outside a provider. */
+    panel?: PortalLocale;
+}
+/**
+ * A picker's language and direction inside a `LocaleProvider`, by the rule a
+ * nested provider follows: its `lang` is its own `locale`, else the
+ * provider's, and its `dir` is the `dir` passed to it, else its own locale's
+ * direction when it has one, else the provider's. Outside a provider it
+ * changes nothing. A `locale` `Intl` refuses counts as none here, since the
+ * picker's own formatting reports it.
+ */
+export declare function usePickerLocaleScope(ownLocale: string | undefined, ownDir: string | undefined): PickerLocaleScope;
+/**
+ * Whether a picker's `dayNames` replace the calendar's own, which `Calendar`
+ * does only for a full week of seven.
+ */
+export declare function hasOwnDayNames(dayNames: string[] | undefined): boolean;
+/**
+ * The day a picker's week starts on: its own `firstDayOfWeek`, else, inside a
+ * `LocaleProvider`, the first day of the locale the picker uses, else Sunday.
+ * Outside a provider it stays Sunday whatever the locale, as it always has,
+ * and so does a picker inside one with no locale from either, since the
+ * runtime's own differs between the server and the browser.
+ *
+ * It also stays Sunday for a picker that brings its own `dayNames`. The
+ * calendar shows those exactly as given, in calendar order, and before the
+ * provider an unset `firstDayOfWeek` was always Sunday, so names written
+ * Sunday first would sit a day or more off their columns if the week moved
+ * under them.
+ */
+export declare function usePickerFirstDayOfWeek(own: DayOfWeek | undefined, locale: string | undefined, hasDayNames: boolean): DayOfWeek;

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

@@ -0,0 +1,128 @@
+import React from 'react';
+import { BulmaClassesProps } from './useBulmaClasses.js';
+/** A writing direction. */
+export type TextDirection = 'ltr' | 'rtl';
+/** What the nearest `LocaleProvider` sets, both `undefined` outside one. */
+export interface LocaleContextValue {
+    /**
+     * The locale, as a canonical BCP 47 tag such as `"ar-EG"`: the provider's
+     * own, else the one an outer provider sets.
+     */
+    locale?: string;
+    /**
+     * The direction: the provider's own `dir`, else its own locale's, else the
+     * one an outer provider sets.
+     */
+    dir?: TextDirection;
+}
+/**
+ * Props for the LocaleProvider component. The helper props, the other
+ * attributes and the `ref` land on its `<div>`.
+ */
+export interface LocaleProviderProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'dir' | 'lang' | 'color'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /**
+     * A BCP 47 language tag, such as `"de"` or `"ar-EG"`. It becomes the
+     * wrapper's `lang`, the default `locale` of the date and time pickers
+     * inside, and, with no `dir`, the direction, from the way its script is
+     * written. Unset, a nested provider keeps the outer one's. A tag `Intl`
+     * refuses is ignored, with a warning in development.
+     */
+    locale?: string;
+    /**
+     * The direction, whatever the locale. Unset, it follows this provider's
+     * `locale`, else an outer provider's direction, else the page's.
+     */
+    dir?: TextDirection;
+    /** The part of the app it covers. */
+    children?: React.ReactNode;
+}
+/**
+ * Sets the language and writing direction for the part of the app inside it, on a wrapper `<div>` and on what the library portals out of it.
+ *
+ * The wrapper carries `dir` and `lang`, so CSS and the components that read
+ * the computed direction follow it, as they follow `<html dir>`. A `locale`
+ * alone sets the direction of its script, and a `dir` sets the direction
+ * whatever the locale. A nested provider keeps whatever it leaves unset.
+ *
+ * Inside it, the date and time pickers take its `locale` unless given their
+ * own, and their week starts on the first day of the locale they use unless
+ * `firstDayOfWeek` is set, and a picker with a `locale` of its own is read
+ * like a nested provider. The library's portaled content, such as a
+ * `Popover` panel, a `Modal` with `portal`, a `Toast` or a `Portal`'s
+ * children, keeps the same `dir` and `lang` though it renders outside the
+ * wrapper: in a container outside the wrapper, it sits in a
+ * `display: contents` element that carries them. Without a provider none of
+ * this changes.
+ *
+ * @function
+ * @param {LocaleProviderProps} props - Props for the LocaleProvider.
+ * @returns {JSX.Element} The wrapper, inside the context.
+ *
+ * @example
+ * <LocaleProvider locale="ar-EG">
+ *   <App />
+ * </LocaleProvider>
+ */
+export declare const LocaleProvider: React.ForwardRefExoticComponent<LocaleProviderProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * The locale and direction the nearest `LocaleProvider` sets, for an app's own `Intl` calls or its own portaled content; both are `undefined` outside one.
+ *
+ * It isn't the page's direction: with no provider, or one that sets no
+ * direction, the page's `<html dir>` still decides. To act on the direction
+ * an element is laid out in, read `getComputedStyle(element).direction`, as
+ * the library's components do.
+ *
+ * @function
+ * @returns {LocaleContextValue} The nearest provider's `locale` and `dir`.
+ *
+ * @example
+ * const { locale } = useLocale();
+ * const price = new Intl.NumberFormat(locale, {
+ *   style: 'currency',
+ *   currency: 'EUR',
+ * }).format(12.5);
+ */
+export declare function useLocale(): LocaleContextValue;
+/**
+ * INTERNAL, deliberately not exported from `src/index.ts`. The nearest
+ * provider's settings, or `null` outside any provider, so a caller can tell
+ * "no provider" from "a provider that sets nothing".
+ */
+export declare function useLocaleScope(): LocaleContextValue | null;
+/** The `dir` and `lang` portaled content carries: a provider's, or a picker's own. */
+export interface PortalLocale {
+    /** The `lang` to carry, unset for none. */
+    locale?: string;
+    /** The `dir` to carry, unset for none. */
+    dir?: string;
+}
+/**
+ * INTERNAL, deliberately not exported from `src/index.ts`. Keeps the `dir`
+ * and `lang` of the nearest provider, or the `scope` given in their place,
+ * on content the library portals into `target`, which has left the
+ * provider's wrapper behind.
+ *
+ * A target inside the provider's own wrapper gets the content as it is: it
+ * inherits from the wrapper, and follows it when the provider changes.
+ * Content that must be its container's direct child, a `<tr>` portaled into
+ * a `<tbody>` there, stays one. Any other target, `document.body` included,
+ * gets the content inside a `display: contents` element carrying the
+ * values, which adds no box. So does content with a `scope` of its own, a
+ * picker's panel, since the provider's values aren't its own.
+ *
+ * Which of the two is decided once, when the content mounts, and kept while
+ * it stays: switching between them would put a different element in its
+ * place and remount everything inside, losing typed text, focus and timers.
+ * A change of locale or direction updates the wrapper's attributes instead.
+ * A target is never left bare because something else, such as `<html>`,
+ * happens to carry the same values, since that can stop being true without
+ * the content remounting. Outside a provider it renders the children alone,
+ * so nothing changes there.
+ */
+export declare function LocalePortalScope({ children, target, scope, }: {
+    children: React.ReactNode;
+    /** The element the content is portaled into. */
+    target: Element;
+    /** Values to carry in place of the provider's, such as a picker's own. */
+    scope?: PortalLocale;
+}): React.JSX.Element;

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

@@ -0,0 +1,23 @@
+import type { DayOfWeek } from '../form/_pickerInternals/pickerTypes.js';
+/**
+ * The canonical form of a BCP 47 tag (`"en-us"` becomes `"en-US"`), or
+ * `undefined` for an empty or missing one. Throws a `RangeError` for a tag
+ * `Intl` refuses, as `Intl.DateTimeFormat` would.
+ */
+export declare function canonicalLocale(tag: string | undefined): string | undefined;
+/**
+ * The direction a locale's script is written in: from `Intl.Locale`'s text
+ * info, else from the script `maximize()` fills in, else from the language.
+ *
+ * @param locale - A canonical tag, as `canonicalLocale` returns.
+ */
+export declare function localeDirection(locale: string): 'ltr' | 'rtl';
+/**
+ * The day a locale's week starts on, 0 for Sunday, as `getWeekInfo()` reads
+ * it: the tag's `-u-fw-` keyword, else the region its `-u-rg-` keyword names,
+ * else its own region or the one `maximize()` fills in, looked up in CLDR's
+ * week data, where a region not listed starts on Monday.
+ *
+ * @param locale - A canonical tag, as `canonicalLocale` returns.
+ */
+export declare function localeFirstDay(locale: string): DayOfWeek;

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

@@ -75,6 +75,17 @@ export interface PortalProps {
  * also reaches what the library's components portal, such as Popover's
  * `appendToBody` panel or a `Modal` with `portal`.
  *
+ * Inside a `LocaleProvider`, the children keep its `dir` and `lang`. A
+ * container inside the provider's own wrapper takes the children as they
+ * are, and they follow the provider through the page. Any other,
+ * `document.body` included, gets them inside one `<div>` carrying the
+ * provider's values, with `display: contents` so it adds no box. It is
+ * still an element, so content that must be the container's direct child,
+ * a `<tr>` in a `<tbody>`, or that a direct-child selector styles, belongs
+ * in a container inside the provider. Which of the two is settled when the
+ * children mount, so a change of locale updates them in place rather than
+ * remounting them.
+ *
  * Tab order and focus follow the DOM too. Content portaled from inside a
  * focus trap is no longer inside the trapped element, so the trap neither
  * reaches it nor holds focus there: render nested overlays inside the

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

@@ -78,6 +78,7 @@ export * from './form/CheckboxCard.js';
 export * from './form/Checkboxes.js';
 export * from './form/Control.js';
 export * from './form/Field.js';
+export * from './form/Fieldset.js';
 export * from './form/File.js';
 export * from './form/Radio.js';
 export * from './form/RadioCard.js';
@@ -133,6 +134,8 @@ export type { ClientOnlyProps } from './helpers/ClientOnly.js';
 export { useIsHydrated } from './helpers/useIsHydrated.js';
 export { Portal } from './helpers/portal.js';
 export type { PortalProps } from './helpers/portal.js';
+export { LocaleProvider, useLocale } from './helpers/LocaleProvider.js';
+export type { LocaleContextValue, LocaleProviderProps, TextDirection, } from './helpers/LocaleProvider.js';
 export { useFocusTrap } from './helpers/useFocusTrap.js';
 export type { UseFocusTrapOptions } from './helpers/useFocusTrap.js';
 export * from './layout/Container.js';