@allxsmith/bestax-bulma 5.52.0 → 5.54.0

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

@@ -0,0 +1,131 @@
+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. With a `locale`, the numbers the library writes,
+ * such as page numbers and badge counts, follow it, and so does the
+ * filtering in `Combobox`, `Autocomplete`, `Taginput` and `Command`, which then ignores
+ * accents where the language treats letters as the same. 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/localeFormat.d.ts

@@ -0,0 +1,26 @@
+/** Formats a number for display, with `Intl.NumberFormat` options. */
+export type NumberFormatter = (value: number, options?: Intl.NumberFormatOptions) => string;
+/** Whether `text` contains `query`, as the locale compares letters. */
+export type TextMatcher = (text: string, query: string) => boolean;
+/**
+ * A formatter for numbers shown on screen, in the locale of the
+ * `LocaleProvider` around the component, or `null` outside one that gives a
+ * locale. Formatters are kept per set of options, since building one is the
+ * expensive part.
+ *
+ * @param own - The component's own locale, such as a picker's `locale`,
+ * which wins inside a provider.
+ */
+export declare function useNumberFormat(own?: string): NumberFormatter | null;
+/**
+ * A matcher for filtering a list by what was typed, in the locale of the
+ * `LocaleProvider` around the component, or `null` outside one that gives a
+ * locale. It compares with `Intl.Collator` at `usage: 'search'` and
+ * `sensitivity: 'base'`, so it ignores case and accents where the language
+ * treats the letters as the same: "cafe" finds "Café", while in Swedish "a"
+ * doesn't find "å", a letter of its own there. Marks the language ignores
+ * count for nothing on either side, so in Arabic محمد finds مُحَمَّد and the
+ * other way round. An empty query, or one of nothing but such marks,
+ * matches everything.
+ */
+export declare function useLocaleMatcher(): TextMatcher | null;

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