@allxsmith/bestax-bulma 5.60.0 → 5.61.0

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

@@ -151,6 +151,7 @@ export { useNumberFormat } from './helpers/localeFormat.js';
 export type { NumberFormatFunction } from './helpers/localeFormat.js';
 export { useFocusTrap } from './helpers/useFocusTrap.js';
 export type { UseFocusTrapOptions } from './helpers/useFocusTrap.js';
+export * from './layout/AppFrame.js';
 export * from './layout/Center.js';
 export * from './layout/Container.js';
 export * from './layout/Flex.js';

package/dist/types-cjs/layout/AppFrame.d.ts

@@ -0,0 +1,306 @@
+import React from 'react';
+import { BulmaClassesProps, validColors } from '../helpers/useBulmaClasses.js';
+import type { NavbarBurgerProps } from '../components/Navbar.js';
+import type { ContainerBreakpoint } from './Container.js';
+/**
+ * The strings AppFrame renders, each with an English default. A key left
+ * out, or set to an empty string, keeps its default.
+ */
+export interface AppFrameLabels {
+    /**
+     * The skip link's text.
+     * @defaultValue 'Skip to main content'
+     */
+    skipLink?: string;
+    /**
+     * The nav's accessible name, when `AppFrame.Nav` has no `aria-label` or
+     * `aria-labelledby`. Leave the word "navigation" out: the role says it.
+     * @defaultValue 'Sections'
+     */
+    nav?: string;
+    /**
+     * The name of the close button at the top of the drawer.
+     * @defaultValue 'Close navigation'
+     */
+    closeNav?: string;
+    /**
+     * The burger's name, when `AppFrame.Burger` has no `aria-label`.
+     * @defaultValue 'menu', Navbar.Burger's
+     */
+    burger?: string;
+}
+/**
+ * Props for the AppFrame component. The helper props, the other attributes
+ * and the `ref` land on the root `<div>`.
+ *
+ * @extraProp {React.Ref<HTMLDivElement>} [ref] - Ref forwarded to the root `<div>`.
+ */
+export interface AppFrameProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'color'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /**
+     * The parts, each a direct child: `Header`, `Nav`, `Main`, `Aside` and
+     * `Footer`, in that order, since it's the Tab order. The frame reads the
+     * `id` of `Main` and `Nav` off its children for the skip link and the
+     * burger, so a part wrapped in a component of your own takes no `id` of
+     * its own. Put the frame at the top of the page, outside any `main` or
+     * sectioning element.
+     */
+    children?: React.ReactNode;
+    /**
+     * The width from which the nav is a column beside the page. Below it, the
+     * nav is a drawer the burger opens. The stylesheet switches the layout at
+     * Bulma's breakpoint, and the script reads the width at Bulma's default
+     * breakpoints, so a theme that moves Bulma's breakpoints moves the layout
+     * but not which state the burger toggles.
+     * @defaultValue 'desktop'
+     */
+    breakpoint?: ContainerBreakpoint;
+    /**
+     * Whether the drawer is open, below the breakpoint. With it, the state is
+     * yours: update it from `onNavOpenChange`. It has no effect from the
+     * breakpoint up, where the frame asks to close it.
+     */
+    navOpen?: boolean;
+    /** Whether the drawer starts open. */
+    defaultNavOpen?: boolean;
+    /**
+     * Called with the state asked for: by the burger, `useAppFrame()`, Escape,
+     * a press outside, the close button, a followed link (see
+     * `AppFrame.Nav`'s `closeOnNavigate`), or the window being at or past the
+     * breakpoint while it's open, which closes it.
+     */
+    onNavOpenChange?: (open: boolean) => void;
+    /**
+     * Whether the column is collapsed out of view, from the breakpoint up.
+     * With it, the state is yours: update it from `onNavCollapsedChange`. It
+     * has no effect below the breakpoint, where the drawer always shows the
+     * whole nav.
+     */
+    navCollapsed?: boolean;
+    /** Whether the column starts collapsed. */
+    defaultNavCollapsed?: boolean;
+    /** Called with the state asked for, by the burger or `useAppFrame()`. */
+    onNavCollapsedChange?: (collapsed: boolean) => void;
+    /**
+     * Renders a skip link first, visible when it has focus, that moves focus
+     * to `AppFrame.Main`. Turn it off only for a page that has its own.
+     */
+    skipLink?: boolean;
+    /** The strings the frame renders. Each one left out keeps its English default. */
+    labels?: AppFrameLabels;
+    /** Text color helper. */
+    textColor?: (typeof validColors)[number] | 'inherit' | 'current';
+    /** Background color helper. */
+    bgColor?: (typeof validColors)[number] | 'inherit' | 'current';
+}
+/**
+ * Props for AppFrame.Header, on its `<header>`, which sticks to the top.
+ *
+ * @extraProp {React.Ref<HTMLElement>} [ref] - Ref forwarded to the `<header>`.
+ */
+export interface AppFrameHeaderProps extends Omit<React.HTMLAttributes<HTMLElement>, 'color'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /**
+     * Usually a `Navbar`, not `fixed`, with `AppFrame.Burger` in its
+     * `Navbar.Brand`. A header taller than Bulma's navbar sets
+     * `--bulma-app-frame-header-height` on `:root`, so the nav column, an
+     * in-page link and focus clear it.
+     */
+    children?: React.ReactNode;
+}
+/**
+ * Props for AppFrame.Nav, on its `<nav>`.
+ *
+ * @extraProp {React.Ref<HTMLElement>} [ref] - Ref forwarded to the `<nav>`.
+ * @extraProp {string} [id] - The nav's id, which the burger's `aria-controls` points at. The frame makes one when there's none.
+ * @extraProp {string} [aria-label] - The nav's name. Without it or `aria-labelledby`, it's the frame's `labels.nav`, "Sections".
+ */
+export interface AppFrameNavProps extends Omit<React.HTMLAttributes<HTMLElement>, 'color'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /**
+     * Usually a `Menu`. A nav taller than the window scrolls on its own. With
+     * `overlay`, the rest of the frame is inert while the drawer is open, so an
+     * overlay opened from the drawer, such as a `Modal`, goes inside the nav or
+     * renders outside the frame (Modal's `portal`).
+     */
+    children?: React.ReactNode;
+    /**
+     * The column's width, and the drawer's up to the window's width less a
+     * strip of backdrop. A number is pixels, and a string any CSS length. It
+     * writes `--bulma-app-frame-nav-width`, 16rem by default.
+     */
+    width?: number | string;
+    /**
+     * Shows a backdrop behind the drawer and makes it modal: Tab stays inside,
+     * the page scroll locks, and the rest of the frame is inert, while what
+     * renders outside it, such as a Modal opened from the drawer or a toast,
+     * stays live. Without it the drawer covers the page without holding Tab,
+     * and focus can move to the page beside it. Either way focus moves in as
+     * it opens. Sidebar's `overlay`.
+     */
+    overlay?: boolean;
+    /**
+     * Closes the drawer on Escape, while it's the topmost overlay, so Escape
+     * closes one layer at a time.
+     */
+    closeOnEscape?: boolean;
+    /**
+     * Closes the drawer on a press outside it while it's the topmost overlay:
+     * a click on the backdrop, or without `overlay` a press anywhere outside
+     * it. Focus goes back to the burger as it closes. Without `overlay`, the
+     * press's own mousedown then moves it, as on any page: to what was pressed
+     * if that takes focus, and otherwise off the burger to the page. A touch
+     * that scrolls leaves it on the burger. A press on a control whose
+     * `aria-controls` names the nav, such as the burger, is left to that
+     * control. Popover's `closeOnClickOutside`.
+     */
+    closeOnClickOutside?: boolean;
+    /**
+     * Closes the drawer when a link inside it is followed with a plain click:
+     * not with a modifier key held, and not on a link with a `target` other
+     * than `_self` or a `download`. Only a link the nav holds in the page
+     * counts, not one in a Modal or a popup it portals elsewhere. Focus goes
+     * back to the burger, and the navigation takes it from there: a router
+     * that moves focus on navigation moves it, and an in-page `#` link leaves
+     * it at its target, as it does anywhere on the page. Turn it off for a
+     * drawer of filters rather than links.
+     */
+    closeOnNavigate?: boolean;
+}
+/**
+ * Props for AppFrame.Main, on the page's one `<main>`. Don't put another
+ * `<main>` inside it. It takes your `id`, or a generated one, for the skip
+ * link, and `tabIndex={-1}` so the link can move focus to it.
+ *
+ * @extraProp {React.Ref<HTMLElement>} [ref] - Ref forwarded to the `<main>`.
+ * @extraProp {string} [id] - Its id, which the skip link points at. The frame makes one when there's none.
+ */
+export interface AppFrameMainProps extends Omit<React.HTMLAttributes<HTMLElement>, 'color'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /** The page. A `Container` or a `Section` inside it gives Bulma's widths and padding. */
+    children?: React.ReactNode;
+}
+/**
+ * Props for AppFrame.Aside, on its `<aside>`, a complementary landmark.
+ * Give it an `aria-label` when the page has more than one.
+ *
+ * @extraProp {React.Ref<HTMLElement>} [ref] - Ref forwarded to the `<aside>`.
+ */
+export interface AppFrameAsideProps extends Omit<React.HTMLAttributes<HTMLElement>, 'color'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /** What sits beside the page: an outline, details, filters. */
+    children?: React.ReactNode;
+    /**
+     * Its width from the breakpoint up; below it, the aside moves under the
+     * page. A number is pixels, and a string any CSS length. It writes
+     * `--bulma-app-frame-aside-width`, 20rem by default.
+     */
+    width?: number | string;
+}
+/**
+ * Props for AppFrame.Footer, on its `<footer>`.
+ *
+ * @extraProp {React.Ref<HTMLElement>} [ref] - Ref forwarded to the `<footer>`.
+ */
+export interface AppFrameFooterProps extends Omit<React.HTMLAttributes<HTMLElement>, 'color'>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
+    /** Plain content, or bestax's `Footer` with `as="div"` for Bulma's footer look. */
+    children?: React.ReactNode;
+}
+/**
+ * Props for AppFrame.Burger: Navbar.Burger's, less the state the frame
+ * fills in. Its `<button>` opens and closes the drawer below the breakpoint
+ * and collapses and expands the column from it up, with `aria-expanded` and
+ * `aria-controls` following the nav. It shows at every width. Hide it from
+ * the breakpoint up with the visibility helpers when the column never
+ * collapses. Outside an AppFrame it controls nothing.
+ */
+export type AppFrameBurgerProps = Omit<NavbarBurgerProps, 'active' | 'aria-expanded' | 'aria-controls'>;
+/** What `useAppFrame()` returns. */
+export interface AppFrameState {
+    /** Whether the drawer is open. */
+    navOpen: boolean;
+    /** Asks to open or close the drawer, through `onNavOpenChange`. */
+    setNavOpen: (open: boolean) => void;
+    /** Whether the column is collapsed. */
+    navCollapsed: boolean;
+    /** Asks to collapse or expand the column, through `onNavCollapsedChange`. */
+    setNavCollapsed: (collapsed: boolean) => void;
+    /**
+     * Whether the nav is a drawer at the current width. `false` on the server
+     * and until the first layout effect has read the width.
+     */
+    isDrawer: boolean;
+    /** Toggles whichever state applies at the current width, as the burger does. */
+    toggleNav: () => void;
+    /** The nav's `id`, for a custom toggle's `aria-controls`. */
+    navId: string;
+}
+/**
+ * The top bar of an AppFrame, which sticks while the page scrolls.
+ *
+ * @function
+ * @param {AppFrameHeaderProps} props - Props for AppFrame.Header.
+ * @param {React.Ref<HTMLElement>} ref - Forwarded ref to the `<header>`.
+ * @returns {JSX.Element} The rendered header.
+ */
+export declare const AppFrameHeader: React.ForwardRefExoticComponent<AppFrameHeaderProps & React.RefAttributes<HTMLElement>>;
+/**
+ * The navigation of an AppFrame: a column beside the page from the breakpoint up, and a drawer below it.
+ *
+ * @function
+ * @param {AppFrameNavProps} props - Props for AppFrame.Nav.
+ * @param {React.Ref<HTMLElement>} ref - Forwarded ref to the `<nav>`.
+ * @returns {JSX.Element} The rendered nav, and the drawer's backdrop.
+ */
+export declare const AppFrameNav: React.ForwardRefExoticComponent<AppFrameNavProps & React.RefAttributes<HTMLElement>>;
+/**
+ * The page's main content in an AppFrame, which the skip link moves focus to.
+ *
+ * @function
+ * @param {AppFrameMainProps} props - Props for AppFrame.Main.
+ * @param {React.Ref<HTMLElement>} ref - Forwarded ref to the `<main>`.
+ * @returns {JSX.Element} The rendered main.
+ */
+export declare const AppFrameMain: React.ForwardRefExoticComponent<AppFrameMainProps & React.RefAttributes<HTMLElement>>;
+/**
+ * Content beside the page in an AppFrame, which moves under it below the breakpoint.
+ *
+ * @function
+ * @param {AppFrameAsideProps} props - Props for AppFrame.Aside.
+ * @param {React.Ref<HTMLElement>} ref - Forwarded ref to the `<aside>`.
+ * @returns {JSX.Element} The rendered aside.
+ */
+export declare const AppFrameAside: React.ForwardRefExoticComponent<AppFrameAsideProps & React.RefAttributes<HTMLElement>>;
+/**
+ * The bottom of an AppFrame, under the page.
+ *
+ * @function
+ * @param {AppFrameFooterProps} props - Props for AppFrame.Footer.
+ * @param {React.Ref<HTMLElement>} ref - Forwarded ref to the `<footer>`.
+ * @returns {JSX.Element} The rendered footer.
+ */
+export declare const AppFrameFooter: React.ForwardRefExoticComponent<AppFrameFooterProps & React.RefAttributes<HTMLElement>>;
+/**
+ * The button that opens the drawer, or collapses the column from the breakpoint up: Navbar.Burger, wired to the frame.
+ *
+ * @function
+ * @param {AppFrameBurgerProps} props - Props for AppFrame.Burger.
+ * @param {React.Ref<HTMLButtonElement>} ref - Forwarded ref to the `<button>`.
+ * @returns {JSX.Element} The rendered burger.
+ */
+export declare const AppFrameBurger: React.ForwardRefExoticComponent<AppFrameBurgerProps & React.RefAttributes<HTMLButtonElement>>;
+/**
+ * The frame's state, for a control of your own inside it: whether the
+ * drawer is open and the column collapsed, setters that go through the
+ * frame's callbacks, and `toggleNav()`, which does what the burger does.
+ * Outside an AppFrame it's `null`, as the library's other context hooks
+ * are, so a control that can sit outside one renders a fallback or nothing.
+ *
+ * @function useAppFrame
+ * @returns The frame's state, or `null` outside an AppFrame.
+ */
+export declare function useAppFrame(): AppFrameState | null;
+export declare const AppFrame: React.ForwardRefExoticComponent<AppFrameProps & React.RefAttributes<HTMLDivElement>> & {
+    Header: React.ForwardRefExoticComponent<AppFrameHeaderProps & React.RefAttributes<HTMLElement>>;
+    Nav: React.ForwardRefExoticComponent<AppFrameNavProps & React.RefAttributes<HTMLElement>>;
+    Main: React.ForwardRefExoticComponent<AppFrameMainProps & React.RefAttributes<HTMLElement>>;
+    Aside: React.ForwardRefExoticComponent<AppFrameAsideProps & React.RefAttributes<HTMLElement>>;
+    Footer: React.ForwardRefExoticComponent<AppFrameFooterProps & React.RefAttributes<HTMLElement>>;
+    Burger: React.ForwardRefExoticComponent<AppFrameBurgerProps & React.RefAttributes<HTMLButtonElement>>;
+};
+export default AppFrame;