@hackcove/ui-react 0.8.3 → 0.9.0

package/README.md

@@ -172,10 +172,14 @@ import { AppShell, PageHeader, Section, Stack, Tabs, appShellRootClassFor } from
 </html>;
 ```
 
-- **`AppShell`** is the page frame: a sticky header that is always one `h-14` row (a nav that does
-  not fit scrolls sideways, it never wraps, and the edge with more to scroll to fades out until it
-  is reached), an optional `subnav` second row (same rule), `main`
-  with fixed `py-8`, and an optional `footer`. The header row is filled by slots, left to right:
+- **`AppShell`** is the page frame: a sticky header that is one `h-14` row on a phone and, from
+  `md`, an `h-14` row plus an `h-12` `subnav` row. On a phone `nav` and `subnav` fold behind one
+  **Menu** button (a native `<details>`, so it opens with no JavaScript, on the keyboard and for a
+  screen reader; Escape closes it and a followed link closes it). The panel hangs below the header
+  and never changes its height, nothing wraps and nothing scrolls sideways. `menuLabel` renames the
+  button (default `Menu`). From `md` the nav and the subnav are rows again (a row wider than the
+  screen scrolls sideways, never wraps, and the edge with more to reach fades out). `main`
+  has fixed `py-8`, and an optional `footer`. The header row is filled by slots, left to right:
   `brand` (logo and name, at the brand type with the logo gap), `nav` (pill `Tabs` of links), `header` (a
   free node, the escape hatch) and `controls` (end-aligned, `gap-2`, centred): no wrapper and
   no styling. Nothing in `controls` shrinks, and a full-width control there (a `Select` at its

package/dist/AppShell.d.ts

@@ -72,18 +72,30 @@ export declare function AppShellHideBelow({ breakpoint, children, ...rest }: Pas
  * the slots do not cover), then `controls`, pushed to the end. An app writes no wrapper or
  * styling for any of them: an item that only fits a wide screen goes in `AppShellHideBelow`. A bar
  * that sticks under the header as the page scrolls is a `StickyBar`.
+ *
+ * On a phone (below `md`) the header is one 56px row at every page: `brand`, `header`, `controls`
+ * and a "Menu" button (`menuLabel`), and `nav` and `subnav` move into that menu, so every link is
+ * reachable and nothing scrolls sideways. The menu is a native `<details>`, so it works with the
+ * keyboard, with a screen reader and on a page that never hydrates. From `md` the header is the
+ * row, and the `subnav` row, as they are.
  */
-export declare function AppShell({ brand, nav, controls, header, subnav, footer, bleed, hideChromeInPrint, children, ...rest }: {
+export declare function AppShell({ brand, nav, controls, header, subnav, menuLabel, footer, bleed, hideChromeInPrint, children, ...rest }: {
     /** The brand: a logo and a name, in the header's brand type, with the gap between them. `AppShellBrand` makes both one link. */
     brand?: ReactNode;
-    /** The main navigation, e.g. a `Tabs variant="pill"` of links (it is already a `<nav>`). */
+    /** The main navigation, e.g. a `Tabs variant="pill"` of links (it is already a `<nav>`). Below `md` it is in the menu. */
     nav?: ReactNode;
     /** The end of the row: a picker, a theme toggle. Gap-2, vertically centred; no child shrinks, and a full-width control (a `Select` at its default) sizes to its content. */
     controls?: ReactNode;
     /** The escape hatch: a free node in the header row, after `brand` and `nav`. */
     header?: ReactNode;
-    /** A second fixed-height row under the header, e.g. a `Tabs variant="pill"` of links. */
+    /** A second fixed-height row under the header from `md`, e.g. a `Tabs variant="pill"` of links. Below `md` it is in the menu with `nav`. */
     subnav?: ReactNode;
+    /**
+     * The phone menu button's name, for an app in another language. Only drawn below `md`, and only
+     * when `nav` or `subnav` is given.
+     * @default Menu
+     */
+    menuLabel?: string;
     /** The page footer: small muted text in a `Container`, under a hairline. Hidden in print with `hideChromeInPrint`. */
     footer?: ReactNode;
     /** Main without a Container, for a full-bleed layout. */

package/dist/AppShell.js

@@ -1,5 +1,6 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useRef } from "react";
+import { AppShellMenu } from "./AppShellMenu.js";
 import { ContainerFrame } from "./Container.js";
 import { schemeClass } from "./colourScheme.js";
 import { cx, focusRing } from "./cx.js";
@@ -46,12 +47,13 @@ const SHOWN_FROM = {
 export function AppShellHideBelow({ breakpoint = "sm", children, ...rest }) {
     return (_jsx("span", { ...rest, className: cx(SHOWN_FROM[breakpoint], "items-center gap-2"), children: children }));
 }
-// One fixed-height row that scrolls sideways and never wraps; its children keep their width.
-const ROW = "flex items-center gap-4 overflow-x-auto whitespace-nowrap *:shrink-0";
-// While a row has more to scroll to on a side, that edge fades out (a mask, so it follows any theme).
-// `ScrollRow` sets `data-more-start` / `data-more-end` (and `data-more` for either); a row that fits
-// has none and is untouched.
-const FADE = "data-more-start:[--fade-start:2rem] data-more-end:[--fade-end:2rem] data-more:[mask-image:linear-gradient(to_right,transparent,#000_var(--fade-start,0px),#000_calc(100%_-_var(--fade-end,0px)),transparent)]";
+// One fixed-height row that never wraps; its children keep their width. From `md` it scrolls sideways
+// if it must; below `md` nothing in the header scrolls (the nav is in the menu), so it only clips.
+const ROW = "items-center gap-4 overflow-x-clip whitespace-nowrap md:overflow-x-auto *:shrink-0";
+// From `md`, while a row has more to scroll to on a side, that edge fades out (a mask, so it follows
+// any theme). `ScrollRow` sets `data-more-start` / `data-more-end` (and `data-more` for either); a
+// row that fits has none and is untouched. Below `md` there is no mask, which would clip the menu.
+const FADE = "md:data-more-start:[--fade-start:2rem] md:data-more-end:[--fade-end:2rem] md:data-more:[mask-image:linear-gradient(to_right,transparent,#000_var(--fade-start,0px),#000_calc(100%_-_var(--fade-end,0px)),transparent)]";
 /** A row in a Container, with the fade on whichever side still has content to scroll to. */
 function ScrollRow({ className, children }) {
     const row = useRef(null);
@@ -81,9 +83,18 @@ function ScrollRow({ className, children }) {
     });
     return (_jsx(ContainerFrame, { elementRef: (el) => void (row.current = el), className: cx(ROW, FADE, className), children: children }));
 }
-/** The header row's slots in order: brand, nav, the free `children`, then controls at the end. */
-function HeaderSlots({ brand, nav, controls, children, }) {
-    return (_jsxs(_Fragment, { children: [brand && (_jsx("div", { className: "flex items-center gap-2 text-base font-bold tracking-tight text-slate-900", children: brand })), nav, children, controls && (_jsx("div", { className: "ml-auto flex items-center gap-2 *:shrink-0 [&>.w-full]:w-auto", children: controls }))] }));
+/**
+ * The header row's slots in order: brand, nav (from `md`), the free `children`, then controls and,
+ * below `md`, the menu at the end.
+ */
+function HeaderSlots({ brand, nav, controls, menu, children, }) {
+    return (_jsxs(_Fragment, { children: [brand && (_jsx("div", { className: "flex items-center gap-2 text-base font-bold tracking-tight text-slate-900", children: brand })), nav && _jsx("div", { className: "hidden items-center gap-4 *:shrink-0 md:flex", children: nav }), children, (controls || menu) && (_jsxs("div", { className: controls
+                    ? "ml-auto flex items-center gap-2 *:shrink-0 [&>.w-full]:w-auto"
+                    : "ml-auto flex items-center gap-2 *:shrink-0 md:hidden", children: [controls, menu] }))] }));
+}
+/** The sticky header: the one-row slots, and from `md` the `subnav` row under them. */
+function AppShellHeader({ brand, nav, controls, subnav, menuLabel, hideChromeInPrint, children, }) {
+    return (_jsxs("header", { className: cx("sticky top-0 z-10 border-b border-slate-200 bg-white", hideChromeInPrint && "print:hidden"), children: [_jsx(ScrollRow, { className: "flex h-14", children: _jsx(HeaderSlots, { brand: brand, nav: nav, controls: controls, menu: (nav || subnav) && (_jsxs(AppShellMenu, { label: menuLabel, children: [nav, subnav] })), children: children }) }), subnav && _jsx(ScrollRow, { className: "hidden h-12 md:flex", children: subnav })] }));
 }
 /**
  * The page frame: it paints the page canvas and sets the type face, ink and font smoothing
@@ -98,9 +109,16 @@ function HeaderSlots({ brand, nav, controls, children, }) {
  * the slots do not cover), then `controls`, pushed to the end. An app writes no wrapper or
  * styling for any of them: an item that only fits a wide screen goes in `AppShellHideBelow`. A bar
  * that sticks under the header as the page scrolls is a `StickyBar`.
+ *
+ * On a phone (below `md`) the header is one 56px row at every page: `brand`, `header`, `controls`
+ * and a "Menu" button (`menuLabel`), and `nav` and `subnav` move into that menu, so every link is
+ * reachable and nothing scrolls sideways. The menu is a native `<details>`, so it works with the
+ * keyboard, with a screen reader and on a page that never hydrates. From `md` the header is the
+ * row, and the `subnav` row, as they are.
  */
-export function AppShell({ brand, nav, controls, header, subnav, footer, bleed = false, hideChromeInPrint = false, children, ...rest }) {
+export function AppShell({ brand, nav, controls, header, subnav, menuLabel = "Menu", footer, bleed = false, hideChromeInPrint = false, children, ...rest }) {
     return (_jsxs("div", { ...rest, className: cx("flex min-h-dvh flex-col bg-gray-50 font-sans text-slate-900 antialiased", 
         // The sticky header's height (its rows and the bottom border), for a bar that sticks under it.
-        subnav ? "[--app-header:calc(6.5rem+1px)]" : "[--app-header:calc(3.5rem+1px)]"), children: [_jsxs("header", { className: cx("sticky top-0 z-10 border-b border-slate-200 bg-white", hideChromeInPrint && "print:hidden"), children: [_jsx(ScrollRow, { className: "h-14", children: _jsx(HeaderSlots, { brand: brand, nav: nav, controls: controls, children: header }) }), subnav && _jsx(ScrollRow, { className: "h-12", children: subnav })] }), _jsx("main", { className: "flex flex-1 flex-col", children: bleed ? (children) : (_jsx(ContainerFrame, { className: cx("py-8", hideChromeInPrint && "print:p-0"), children: children })) }), footer && (_jsx("footer", { className: cx("border-t border-slate-200", hideChromeInPrint && "print:hidden"), children: _jsx(ContainerFrame, { className: "py-6 text-sm text-slate-500", children: footer }) }))] }));
+        // Below `md` it is one row whatever the slots are: the subnav is in the menu.
+        "[--app-header:calc(3.5rem+1px)]", subnav ? "md:[--app-header:calc(6.5rem+1px)]" : undefined), children: [_jsx(AppShellHeader, { brand: brand, nav: nav, controls: controls, subnav: subnav, menuLabel: menuLabel, hideChromeInPrint: hideChromeInPrint, children: header }), _jsx("main", { className: "flex flex-1 flex-col", children: bleed ? (children) : (_jsx(ContainerFrame, { className: cx("py-8", hideChromeInPrint && "print:p-0"), children: children })) }), footer && (_jsx("footer", { className: cx("border-t border-slate-200", hideChromeInPrint && "print:hidden"), children: _jsx(ContainerFrame, { className: "py-6 text-sm text-slate-500", children: footer }) }))] }));
 }

package/dist/AppShellMenu.d.ts

@@ -0,0 +1,13 @@
+import { type ReactElement, type ReactNode } from "react";
+/**
+ * The header's phone menu (below `md`): a native `<details>` whose `<summary>` is the button, so it
+ * opens and closes by pointer, Enter and Space, and is announced as a disclosure with its expanded
+ * state, all with no script. That is why it also works on a page that is never hydrated. The panel
+ * is out of flow (it hangs under the header, `top-full`), so the header keeps its one height open
+ * or closed. With script it also closes on Escape (focus returns to the button) and when a link in
+ * it is followed, for a router that changes the page without a reload.
+ */
+export declare function AppShellMenu({ label, children, }: {
+    label: string;
+    children: ReactNode;
+}): ReactElement;

package/dist/AppShellMenu.js

@@ -0,0 +1,42 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef } from "react";
+import { ContainerFrame } from "./Container.js";
+import { cx, focusRing } from "./cx.js";
+const ICON = {
+    viewBox: "0 0 20 20",
+    width: 16,
+    height: 16,
+    fill: "none",
+    stroke: "currentColor",
+    strokeWidth: 1.8,
+    strokeLinecap: "round",
+    strokeLinejoin: "round",
+    "aria-hidden": true,
+    className: "shrink-0 text-slate-500",
+};
+/**
+ * The header's phone menu (below `md`): a native `<details>` whose `<summary>` is the button, so it
+ * opens and closes by pointer, Enter and Space, and is announced as a disclosure with its expanded
+ * state, all with no script. That is why it also works on a page that is never hydrated. The panel
+ * is out of flow (it hangs under the header, `top-full`), so the header keeps its one height open
+ * or closed. With script it also closes on Escape (focus returns to the button) and when a link in
+ * it is followed, for a router that changes the page without a reload.
+ */
+export function AppShellMenu({ label, children, }) {
+    const details = useRef(null);
+    const close = (focusButton) => {
+        const el = details.current;
+        if (!el?.open)
+            return;
+        el.open = false;
+        if (focusButton)
+            el.querySelector("summary")?.focus();
+    };
+    return (_jsxs("details", { ref: details, className: "group md:hidden", onKeyDown: (event) => {
+            if (event.key === "Escape")
+                close(true);
+        }, children: [_jsxs("summary", { className: cx("flex cursor-pointer list-none items-center gap-2 rounded-lg border border-slate-300 bg-white px-3 py-2 text-sm font-medium text-slate-900 select-none hover:bg-slate-50 [&::-webkit-details-marker]:hidden", focusRing), children: [_jsx("svg", { ...ICON, className: cx(ICON.className, "group-open:hidden"), children: _jsx("path", { d: "M3 5.5h14M3 10h14M3 14.5h14" }) }), _jsx("svg", { ...ICON, className: cx(ICON.className, "hidden group-open:block"), children: _jsx("path", { d: "M5 5l10 10M15 5L5 15" }) }), label] }), _jsx("div", { className: "absolute inset-x-0 top-full max-h-[calc(100dvh-var(--app-header))] overflow-y-auto overscroll-contain border-y border-slate-200 bg-white shadow-lg", onClick: (event) => {
+                    if (event.target instanceof Element && event.target.closest("a[href]"))
+                        close(false);
+                }, children: _jsx(ContainerFrame, { className: "flex flex-col gap-3 py-3", children: children }) })] }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hackcove/ui-react",
-  "version": "0.8.3",
+  "version": "0.9.0",
   "description": "Hack Cove React components: primitives, typography roles and a safe Markdown renderer, written against Tailwind v4 utilities. Pair with a @hackcove/theme-* package.",
   "keywords": [
     "components",