@allxsmith/bestax-bulma 5.18.1 → 5.18.2

package/dist/types/components/Avatar.d.ts

@@ -114,6 +114,9 @@ export type AvatarProps<T extends React.ElementType = 'figure'> = Omit<AvatarOwn
      * `role="img"`. A role claiming the opposite, such as `"button"`, says nothing here, and
      * neither does an `href`: that settles it on its own. A genuine `'a'`/`'button'`/`href`
      * avatar keeps its accessible name either way.
+     *
+     * `'button'` renders `type="button"` unless you pass `type="submit"` or `type="reset"`, so
+     * an avatar inside a form does not submit it.
      */
     as?: T;
 };

package/dist/types/components/Dropdown.d.ts

@@ -81,7 +81,12 @@ export interface DropdownItemOwnProps extends BulmaClassesProps {
  * `__typetests__/polymorphic.tsx`; the component itself is unaffected.
  */
 export type DropdownItemProps<T extends DropdownItemElement = DropdownItemElement> = DropdownItemOwnProps & Omit<React.ComponentPropsWithoutRef<T>, keyof DropdownItemOwnProps | 'as'> & {
-    /** The element type to render. */
+    /**
+     * The element type to render.
+     *
+     * `'button'` renders `type="button"` unless you pass `type="submit"` or `type="reset"`, so
+     * an item inside a form does not submit it.
+     */
     as?: T;
 };
 /**

package/dist/types/components/Menu.d.ts

@@ -80,7 +80,12 @@ export interface MenuItemOwnProps extends BulmaClassesProps {
  * @extraProp {PolymorphicRef<React.ElementType>} [ref] - Ref forwarded to the inner element `as` renders, not the wrapping `<li>`, typed from `as`: the DOM node for an intrinsic tag, or whatever handle a custom component exposes.
  */
 export type MenuItemProps<T extends React.ElementType = 'a'> = MenuItemOwnProps & Omit<React.ComponentPropsWithoutRef<T>, keyof MenuItemOwnProps | 'as'> & {
-    /** Custom link component (e.g. `Link` from router). */
+    /**
+     * Custom link component (e.g. `Link` from router).
+     *
+     * `'button'` renders `type="button"` unless you pass `type="submit"` or `type="reset"`, so
+     * an item inside a form does not submit it.
+     */
     as?: T;
 };
 /**

package/dist/types/components/Toast.d.ts

@@ -18,8 +18,8 @@ export interface ToastProps extends Omit<React.HTMLAttributes<HTMLDivElement>, '
     actionType?: ToastType;
     /**
      * Position on the screen. Default: 'top-right'. On a standalone `<Toast>`
-     * this places it; through `toast.show()` it is currently ignored, because
-     * `ToastContainer`'s own `position` places every toast it shows.
+     * this places it. Through `toast.show()` it places that toast, and a toast
+     * shown without one goes to `ToastContainer`'s `position` instead.
      */
     position?: ToastPosition;
     /** Duration in ms before auto-close. `0` disables auto-close. */
@@ -72,7 +72,10 @@ export declare const Toast: React.ForwardRefExoticComponent<ToastProps & React.R
 export interface ToastOptions extends Omit<ToastProps, 'message'> {
     /** The message to display. */
     message: string;
-    /** When true, toasts enter a FIFO queue and display one at a time. Default false. */
+    /**
+     * When true, toasts enter a FIFO queue and display one at a time, one queue
+     * across every `position`. Default false.
+     */
     queue?: boolean;
 }
 /**
@@ -142,13 +145,21 @@ export declare const toast: {
 };
 /**
  * Container component for rendering programmatic toasts.
- * Place once at your app root to enable the toast API.
+ * Place once at your app root to enable the toast API. A toast shown with a
+ * `position` appears there, and one shown without goes to the container's
+ * `position`.
  *
  * @function
  * @param {{ position?: ToastPosition }} props - Container props.
  * @returns {JSX.Element | null} The rendered toast container, or null if empty.
  */
 export declare const ToastContainer: React.FC<{
+    /**
+     * Where a toast shown without a `position` of its own appears. Default:
+     * 'top-right'. When it changes, those toasts move without remounting, but
+     * one shown with its own `position` equal to the old or new value
+     * remounts and starts over as if it had just been shown.
+     */
     position?: ToastPosition;
 }>;
 export default Toast;

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

@@ -59,11 +59,14 @@ export interface NotificationOptions {
     /** Duration in ms before auto-close. Default 3000. */
     duration?: number;
     /**
-     * Position on the screen. Currently ignored: `NotificationContainer`'s own
-     * `position` places every notification it shows, so set it there.
+     * Position on the screen. A notification shown without one goes to
+     * `NotificationContainer`'s `position`.
      */
     position?: NotificationPosition;
-    /** When true, notifications enter a FIFO queue and display one at a time. Default false. */
+    /**
+     * When true, notifications enter a FIFO queue and display one at a time,
+     * one queue across every `position`. Default false.
+     */
     queue?: boolean;
     /** Show a delete (close) button. Default true. */
     hasDelete?: boolean;
@@ -139,13 +142,22 @@ export declare const notification: {
 };
 /**
  * Container component for rendering programmatic notifications.
- * Place once at your app root to enable the notification API.
+ * Place once at your app root to enable the notification API. A notification
+ * shown with a `position` appears there, and one shown without goes to the
+ * container's `position`, so the container renders a stack for each position
+ * in use.
  *
  * @function
  * @param {{ position?: NotificationPosition }} props - Container props.
  * @returns {JSX.Element | null} The rendered notification container, or null if empty.
  */
 export declare const NotificationContainer: React.FC<{
+    /**
+     * Where a notification shown without a `position` of its own appears.
+     * Default: 'top-right'. When it changes, those notifications move without
+     * remounting, but one shown with its own `position` equal to the old or new
+     * value remounts and starts over as if it had just been shown.
+     */
     position?: NotificationPosition;
 }>;
 export {};

package/dist/types/helpers/buttonType.d.ts

@@ -0,0 +1,19 @@
+import type React from 'react';
+/** The values HTML defines for a `<button>`'s `type`. */
+export type ButtonType = NonNullable<React.ButtonHTMLAttributes<HTMLButtonElement>['type']>;
+/**
+ * The `type` to render on a `<button>` a component defaults to `button`: the
+ * caller's own value when it is `button`, `submit` or `reset`, and `button`
+ * otherwise.
+ *
+ * A missing `type` is not the only way a button ends up submitting the form
+ * around it. HTML reads an invalid value, such as the anchor's MIME-type
+ * `type="text/html"`, as submit too, and a props spread carrying
+ * `type: undefined` removes the attribute outright. Both can arrive through a
+ * spread or an untyped caller the component's own types never see, so this
+ * checks the value rather than trusting where it came from.
+ *
+ * Call it AFTER the forwarded props are spread and pass it the forwarded
+ * `type`, so its result is the attribute that renders.
+ */
+export declare function buttonType(given: unknown): ButtonType;

package/dist/types/helpers/positionStacks.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The items a programmatic container shows at one place on the screen.
+ */
+export interface PositionStack<Item, Position extends string> {
+    /**
+     * A React key for the stack. The stack at the container's own position
+     * keeps the same key whatever that position is, so changing the container's
+     * `position` moves the items in it instead of remounting them.
+     */
+    key: string;
+    /** Where on the screen the stack sits. */
+    position: Position;
+    /** The items at that position, in the order they were shown. */
+    items: Item[];
+}
+/**
+ * Splits the items a container shows into one stack per position in use. An
+ * item goes to its own position when it has one and to the container's
+ * otherwise. A position with no items gets no stack.
+ *
+ * Stacks come back in `order`, so their order in the page follows the screen
+ * rather than which position happened to be used first, and a stack keeps its
+ * place while the others come and go. A position missing from `order` sorts
+ * after the known ones.
+ *
+ * @function groupIntoPositionStacks
+ * @param items - The items the container shows, in the order they were shown.
+ * @param positionOf - Reads an item's own position, if it has one.
+ * @param containerPosition - Where an item without a position of its own goes.
+ * @param order - Every known position, in the order stacks should render.
+ * @returns One stack per position in use.
+ */
+export declare function groupIntoPositionStacks<Item, Position extends string>(items: readonly Item[], positionOf: (item: Item) => Position | undefined, containerPosition: Position, order: readonly Position[]): PositionStack<Item, Position>[];

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

@@ -114,6 +114,9 @@ export type AvatarProps<T extends React.ElementType = 'figure'> = Omit<AvatarOwn
      * `role="img"`. A role claiming the opposite, such as `"button"`, says nothing here, and
      * neither does an `href`: that settles it on its own. A genuine `'a'`/`'button'`/`href`
      * avatar keeps its accessible name either way.
+     *
+     * `'button'` renders `type="button"` unless you pass `type="submit"` or `type="reset"`, so
+     * an avatar inside a form does not submit it.
      */
     as?: T;
 };

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

@@ -81,7 +81,12 @@ export interface DropdownItemOwnProps extends BulmaClassesProps {
  * `__typetests__/polymorphic.tsx`; the component itself is unaffected.
  */
 export type DropdownItemProps<T extends DropdownItemElement = DropdownItemElement> = DropdownItemOwnProps & Omit<React.ComponentPropsWithoutRef<T>, keyof DropdownItemOwnProps | 'as'> & {
-    /** The element type to render. */
+    /**
+     * The element type to render.
+     *
+     * `'button'` renders `type="button"` unless you pass `type="submit"` or `type="reset"`, so
+     * an item inside a form does not submit it.
+     */
     as?: T;
 };
 /**

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

@@ -80,7 +80,12 @@ export interface MenuItemOwnProps extends BulmaClassesProps {
  * @extraProp {PolymorphicRef<React.ElementType>} [ref] - Ref forwarded to the inner element `as` renders, not the wrapping `<li>`, typed from `as`: the DOM node for an intrinsic tag, or whatever handle a custom component exposes.
  */
 export type MenuItemProps<T extends React.ElementType = 'a'> = MenuItemOwnProps & Omit<React.ComponentPropsWithoutRef<T>, keyof MenuItemOwnProps | 'as'> & {
-    /** Custom link component (e.g. `Link` from router). */
+    /**
+     * Custom link component (e.g. `Link` from router).
+     *
+     * `'button'` renders `type="button"` unless you pass `type="submit"` or `type="reset"`, so
+     * an item inside a form does not submit it.
+     */
     as?: T;
 };
 /**

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

@@ -18,8 +18,8 @@ export interface ToastProps extends Omit<React.HTMLAttributes<HTMLDivElement>, '
     actionType?: ToastType;
     /**
      * Position on the screen. Default: 'top-right'. On a standalone `<Toast>`
-     * this places it; through `toast.show()` it is currently ignored, because
-     * `ToastContainer`'s own `position` places every toast it shows.
+     * this places it. Through `toast.show()` it places that toast, and a toast
+     * shown without one goes to `ToastContainer`'s `position` instead.
      */
     position?: ToastPosition;
     /** Duration in ms before auto-close. `0` disables auto-close. */
@@ -72,7 +72,10 @@ export declare const Toast: React.ForwardRefExoticComponent<ToastProps & React.R
 export interface ToastOptions extends Omit<ToastProps, 'message'> {
     /** The message to display. */
     message: string;
-    /** When true, toasts enter a FIFO queue and display one at a time. Default false. */
+    /**
+     * When true, toasts enter a FIFO queue and display one at a time, one queue
+     * across every `position`. Default false.
+     */
     queue?: boolean;
 }
 /**
@@ -142,13 +145,21 @@ export declare const toast: {
 };
 /**
  * Container component for rendering programmatic toasts.
- * Place once at your app root to enable the toast API.
+ * Place once at your app root to enable the toast API. A toast shown with a
+ * `position` appears there, and one shown without goes to the container's
+ * `position`.
  *
  * @function
  * @param {{ position?: ToastPosition }} props - Container props.
  * @returns {JSX.Element | null} The rendered toast container, or null if empty.
  */
 export declare const ToastContainer: React.FC<{
+    /**
+     * Where a toast shown without a `position` of its own appears. Default:
+     * 'top-right'. When it changes, those toasts move without remounting, but
+     * one shown with its own `position` equal to the old or new value
+     * remounts and starts over as if it had just been shown.
+     */
     position?: ToastPosition;
 }>;
 export default Toast;

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

@@ -59,11 +59,14 @@ export interface NotificationOptions {
     /** Duration in ms before auto-close. Default 3000. */
     duration?: number;
     /**
-     * Position on the screen. Currently ignored: `NotificationContainer`'s own
-     * `position` places every notification it shows, so set it there.
+     * Position on the screen. A notification shown without one goes to
+     * `NotificationContainer`'s `position`.
      */
     position?: NotificationPosition;
-    /** When true, notifications enter a FIFO queue and display one at a time. Default false. */
+    /**
+     * When true, notifications enter a FIFO queue and display one at a time,
+     * one queue across every `position`. Default false.
+     */
     queue?: boolean;
     /** Show a delete (close) button. Default true. */
     hasDelete?: boolean;
@@ -139,13 +142,22 @@ export declare const notification: {
 };
 /**
  * Container component for rendering programmatic notifications.
- * Place once at your app root to enable the notification API.
+ * Place once at your app root to enable the notification API. A notification
+ * shown with a `position` appears there, and one shown without goes to the
+ * container's `position`, so the container renders a stack for each position
+ * in use.
  *
  * @function
  * @param {{ position?: NotificationPosition }} props - Container props.
  * @returns {JSX.Element | null} The rendered notification container, or null if empty.
  */
 export declare const NotificationContainer: React.FC<{
+    /**
+     * Where a notification shown without a `position` of its own appears.
+     * Default: 'top-right'. When it changes, those notifications move without
+     * remounting, but one shown with its own `position` equal to the old or new
+     * value remounts and starts over as if it had just been shown.
+     */
     position?: NotificationPosition;
 }>;
 export {};

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

@@ -0,0 +1,19 @@
+import type React from 'react';
+/** The values HTML defines for a `<button>`'s `type`. */
+export type ButtonType = NonNullable<React.ButtonHTMLAttributes<HTMLButtonElement>['type']>;
+/**
+ * The `type` to render on a `<button>` a component defaults to `button`: the
+ * caller's own value when it is `button`, `submit` or `reset`, and `button`
+ * otherwise.
+ *
+ * A missing `type` is not the only way a button ends up submitting the form
+ * around it. HTML reads an invalid value, such as the anchor's MIME-type
+ * `type="text/html"`, as submit too, and a props spread carrying
+ * `type: undefined` removes the attribute outright. Both can arrive through a
+ * spread or an untyped caller the component's own types never see, so this
+ * checks the value rather than trusting where it came from.
+ *
+ * Call it AFTER the forwarded props are spread and pass it the forwarded
+ * `type`, so its result is the attribute that renders.
+ */
+export declare function buttonType(given: unknown): ButtonType;

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

@@ -0,0 +1,33 @@
+/**
+ * The items a programmatic container shows at one place on the screen.
+ */
+export interface PositionStack<Item, Position extends string> {
+    /**
+     * A React key for the stack. The stack at the container's own position
+     * keeps the same key whatever that position is, so changing the container's
+     * `position` moves the items in it instead of remounting them.
+     */
+    key: string;
+    /** Where on the screen the stack sits. */
+    position: Position;
+    /** The items at that position, in the order they were shown. */
+    items: Item[];
+}
+/**
+ * Splits the items a container shows into one stack per position in use. An
+ * item goes to its own position when it has one and to the container's
+ * otherwise. A position with no items gets no stack.
+ *
+ * Stacks come back in `order`, so their order in the page follows the screen
+ * rather than which position happened to be used first, and a stack keeps its
+ * place while the others come and go. A position missing from `order` sorts
+ * after the known ones.
+ *
+ * @function groupIntoPositionStacks
+ * @param items - The items the container shows, in the order they were shown.
+ * @param positionOf - Reads an item's own position, if it has one.
+ * @param containerPosition - Where an item without a position of its own goes.
+ * @param order - Every known position, in the order stacks should render.
+ * @returns One stack per position in use.
+ */
+export declare function groupIntoPositionStacks<Item, Position extends string>(items: readonly Item[], positionOf: (item: Item) => Position | undefined, containerPosition: Position, order: readonly Position[]): PositionStack<Item, Position>[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allxsmith/bestax-bulma",
-  "version": "5.18.1",
+  "version": "5.18.2",
   "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",