@hackcove/ui-react 0.9.1 → 0.10.0

package/dist/TableEditCell.d.ts

@@ -1,13 +1,15 @@
 import type { ComponentProps, ReactElement, ReactNode } from "react";
 import { TableCell } from "./Table.js";
 /**
- * A `TableCell` whose value opens an editor in place. It shows `children` as a button with a dotted
- * underline; a click, Enter or Space swaps it for `renderEditor(close)` and moves the focus into the
- * editor. The cell keeps its own open state. The editor calls `close` when it has saved, and Esc
- * closes it: both put the focus back on the value. A press outside it or Tab out of it closes it too and leaves the
- * focus where it went, so the editor saves its value on its own change or submit, never on a close.
- * Put the control in the cell itself, not in a popover of its own, which counts as outside. Takes
- * `TableCell`'s `align`, `tone`, `numeric`, `mono`, `indent` and `secondary`.
+ * A `TableCell` whose value opens an editor in place: a cell that holds one `InlineEdit` and
+ * nothing else. It shows `children` as a button with a dotted underline; a click, Enter or Space
+ * swaps it for `renderEditor(close)` and moves the focus into the editor. The editor calls `close`
+ * when it has saved, and Esc closes it: both put the focus back on the value. A press outside it or
+ * Tab out of it closes it too and leaves the focus where it went, so the editor saves its value on
+ * its own change or submit, never on a close. Put the control in the cell itself, not in a popover
+ * of its own, which counts as outside. Takes `TableCell`'s `align`, `tone`, `numeric`, `mono`,
+ * `indent` and `secondary`. For an edit trigger in a cell that holds other content too, put an
+ * `InlineEdit` in a `TableCell`.
  */
 export declare function TableEditCell({ label, renderEditor, children, ...cell }: {
     /** What the button does, for a screen reader, heard after the value: "Edit category". It also names the editor. */

package/dist/TableEditCell.js

@@ -1,58 +1,17 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useEffect, useRef, useState } from "react";
-import { cx, focusRing } from "./cx.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { InlineEdit } from "./InlineEdit.js";
 import { TableCell } from "./Table.js";
-/** What takes the focus when the editor opens, unless the editor already took it (`autoFocus`). */
-const FOCUSABLE = "input, select, textarea, button, a[href]";
-/** Whether `target` is a node outside `box`. */
-function isOutside(box, target) {
-    return target instanceof Node && box !== null && !box.contains(target);
-}
-/** Closes the editor when a press lands outside `box`, for as long as `open`. */
-function useDismissOnOutsidePress(box, open, dismiss) {
-    useEffect(() => {
-        if (!open)
-            return undefined;
-        const onPress = (event) => {
-            if (isOutside(box.current, event.target))
-                dismiss();
-        };
-        document.addEventListener("pointerdown", onPress);
-        return () => document.removeEventListener("pointerdown", onPress);
-    }, [box, open, dismiss]);
-}
 /**
- * A `TableCell` whose value opens an editor in place. It shows `children` as a button with a dotted
- * underline; a click, Enter or Space swaps it for `renderEditor(close)` and moves the focus into the
- * editor. The cell keeps its own open state. The editor calls `close` when it has saved, and Esc
- * closes it: both put the focus back on the value. A press outside it or Tab out of it closes it too and leaves the
- * focus where it went, so the editor saves its value on its own change or submit, never on a close.
- * Put the control in the cell itself, not in a popover of its own, which counts as outside. Takes
- * `TableCell`'s `align`, `tone`, `numeric`, `mono`, `indent` and `secondary`.
+ * A `TableCell` whose value opens an editor in place: a cell that holds one `InlineEdit` and
+ * nothing else. It shows `children` as a button with a dotted underline; a click, Enter or Space
+ * swaps it for `renderEditor(close)` and moves the focus into the editor. The editor calls `close`
+ * when it has saved, and Esc closes it: both put the focus back on the value. A press outside it or
+ * Tab out of it closes it too and leaves the focus where it went, so the editor saves its value on
+ * its own change or submit, never on a close. Put the control in the cell itself, not in a popover
+ * of its own, which counts as outside. Takes `TableCell`'s `align`, `tone`, `numeric`, `mono`,
+ * `indent` and `secondary`. For an edit trigger in a cell that holds other content too, put an
+ * `InlineEdit` in a `TableCell`.
  */
 export function TableEditCell({ label, renderEditor, children, ...cell }) {
-    const [phase, setPhase] = useState("closed");
-    const open = phase === "open";
-    const box = useRef(null);
-    const trigger = useRef(null);
-    const dismiss = useCallback(() => setPhase("closed"), []);
-    const close = () => setPhase("returning");
-    useDismissOnOutsidePress(box, open, dismiss);
-    useEffect(() => {
-        if (phase === "returning")
-            trigger.current?.focus();
-        if (phase === "open" && !box.current?.contains(document.activeElement))
-            box.current?.querySelector(FOCUSABLE)?.focus();
-    }, [phase]);
-    const onKeyDown = (event) => {
-        if (event.key !== "Escape")
-            return;
-        event.preventDefault();
-        event.stopPropagation();
-        close();
-    };
-    return (_jsx(TableCell, { ...cell, children: open ? (_jsx("div", { ref: box, role: "group", "aria-label": label, className: "-mx-2 -my-1", onKeyDown: onKeyDown, onBlur: (event) => {
-                if (isOutside(event.currentTarget, event.relatedTarget))
-                    dismiss();
-            }, children: renderEditor(close) })) : (_jsxs("button", { ref: trigger, type: "button", onClick: () => setPhase("open"), className: cx("-mx-2 -my-1 block w-[calc(100%+1rem)] cursor-pointer rounded-md px-2 py-1 [text-align:inherit] underline decoration-dotted underline-offset-4 transition hover:bg-slate-100", focusRing), children: [children, _jsxs("span", { className: "sr-only", children: [" ", label] })] })) }));
+    return (_jsx(TableCell, { ...cell, children: _jsx(InlineEdit, { label: label, renderEditor: renderEditor, children: children }) }));
 }

package/dist/foldedColumn.d.ts

@@ -0,0 +1,18 @@
+import { type ReactElement, type ReactNode } from "react";
+/** The breakpoint a folded column opens up at: below it the column sits behind a disclosure. */
+export type FoldFrom = "md" | "lg";
+/**
+ * A side column that folds behind a native `<details>` disclosure named `label`, closed, below
+ * `from`, and is the same column, always open, from `from` up. The column stays mounted while it is
+ * folded, so state inside it is kept. Shared by `SidebarLayout` (`md`) and `SideColumn` (`lg`).
+ *
+ * From `from` up the CSS shows the content of the closed `<details>` (the first frame, and a page
+ * that never hydrates). But a closed `<details>` is hidden to the accessibility tree and to axe, so
+ * once mounted an effect also opens it for real from `from` up and closes it again below. There is
+ * no `open` prop, so React never fights the browser's toggle and the server markup stays closed.
+ */
+export declare function FoldedColumn({ from, label, children, }: {
+    from: FoldFrom;
+    label: string;
+    children: ReactNode;
+}): ReactElement;

package/dist/foldedColumn.js

@@ -0,0 +1,45 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef } from "react";
+import { cx, focusRing } from "./cx.js";
+// Each variant is written out whole, so Tailwind sees every class.
+const FOLD = {
+    md: {
+        query: "(width >= 48rem)",
+        content: "md:[&::details-content]:[content-visibility:visible]",
+        summary: "md:hidden",
+        body: "md:mt-0",
+    },
+    lg: {
+        query: "(width >= 64rem)",
+        content: "lg:[&::details-content]:[content-visibility:visible]",
+        summary: "lg:hidden",
+        body: "lg:mt-0",
+    },
+};
+/**
+ * A side column that folds behind a native `<details>` disclosure named `label`, closed, below
+ * `from`, and is the same column, always open, from `from` up. The column stays mounted while it is
+ * folded, so state inside it is kept. Shared by `SidebarLayout` (`md`) and `SideColumn` (`lg`).
+ *
+ * From `from` up the CSS shows the content of the closed `<details>` (the first frame, and a page
+ * that never hydrates). But a closed `<details>` is hidden to the accessibility tree and to axe, so
+ * once mounted an effect also opens it for real from `from` up and closes it again below. There is
+ * no `open` prop, so React never fights the browser's toggle and the server markup stays closed.
+ */
+export function FoldedColumn({ from, label, children, }) {
+    const fold = FOLD[from];
+    const details = useRef(null);
+    useEffect(() => {
+        const el = details.current;
+        if (!el || typeof window.matchMedia !== "function")
+            return undefined;
+        const wide = window.matchMedia(fold.query);
+        const sync = () => {
+            el.open = wide.matches;
+        };
+        sync();
+        wide.addEventListener("change", sync);
+        return () => wide.removeEventListener("change", sync);
+    }, [fold.query]);
+    return (_jsxs("details", { ref: details, className: cx("group", fold.content), children: [_jsxs("summary", { className: cx("flex cursor-pointer list-none items-center justify-between 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", fold.summary, focusRing), children: [label, _jsx("svg", { 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 group-open:rotate-180", children: _jsx("path", { d: "M5 8l5 5 5-5" }) })] }), _jsx("div", { className: cx("mt-2", fold.body), children: children })] }));
+}

package/dist/index.d.ts

@@ -10,7 +10,9 @@ export { Markdown } from "./Markdown.js";
 export { AppShell, AppShellBrand, type AppShellBreakpoint, AppShellHideBelow, appShellRootClassFor, } from "./AppShell.js";
 export { Container } from "./Container.js";
 export { PageHeader, type PageHeaderProps } from "./PageHeader.js";
-export { CardGrid, CenteredLayout, DetailLayout, FormLayout, FullBleedLayout, ListLayout, ProseLayout, SidebarLayout, } from "./PageLayouts.js";
+export { CardGrid, CenteredLayout, DetailLayout, FormLayout, FullBleedLayout, ListLayout, ProseLayout, } from "./PageLayouts.js";
+export { SidebarLayout } from "./SidebarLayout.js";
+export { SideColumn, type SideColumnWidth } from "./SideColumn.js";
 export { StickyBar } from "./StickyBar.js";
 export { ErrorPage, Forbidden, Maintenance, NotFound, Offline } from "./StatusPages.js";
 export { Cluster, ClusterGrow, type ClusterAlign, type ClusterGap, type ClusterJustify, } from "./Cluster.js";
@@ -26,6 +28,7 @@ export { Callout, type CalloutTone } from "./Callout.js";
 export { ListRow, type ListRowProps } from "./ListRow.js";
 export { OutlineRegion, RegionFrame, type RegionRect } from "./OutlineRegion.js";
 export { type CellTone, type RowTone, Table, TableBody, TableCell, TableFoot, TableGroupRow, TableHead, TableHeaderCell, TableRow, } from "./Table.js";
+export { InlineEdit } from "./InlineEdit.js";
 export { TableEditCell } from "./TableEditCell.js";
 export { EmptyState } from "./EmptyState.js";
 export { Step, Steps } from "./Steps.js";
@@ -49,6 +52,7 @@ export { Tabs, type Tab, type TabsProps } from "./Tabs.js";
 export { SegmentedControl, type Segment } from "./SegmentedControl.js";
 export { FilterGroup } from "./FilterGroup.js";
 export { Checkbox } from "./Checkbox.js";
+export { Switch } from "./Switch.js";
 export { Radio, RadioGroup } from "./RadioGroup.js";
 export { FileDrop } from "./FileDrop.js";
 export { CopyButton } from "./CopyButton.js";

package/dist/index.js

@@ -10,7 +10,9 @@ export { Markdown } from "./Markdown.js";
 export { AppShell, AppShellBrand, AppShellHideBelow, appShellRootClassFor, } from "./AppShell.js";
 export { Container } from "./Container.js";
 export { PageHeader } from "./PageHeader.js";
-export { CardGrid, CenteredLayout, DetailLayout, FormLayout, FullBleedLayout, ListLayout, ProseLayout, SidebarLayout, } from "./PageLayouts.js";
+export { CardGrid, CenteredLayout, DetailLayout, FormLayout, FullBleedLayout, ListLayout, ProseLayout, } from "./PageLayouts.js";
+export { SidebarLayout } from "./SidebarLayout.js";
+export { SideColumn } from "./SideColumn.js";
 export { StickyBar } from "./StickyBar.js";
 export { ErrorPage, Forbidden, Maintenance, NotFound, Offline } from "./StatusPages.js";
 export { Cluster, ClusterGrow, } from "./Cluster.js";
@@ -26,6 +28,7 @@ export { Callout } from "./Callout.js";
 export { ListRow } from "./ListRow.js";
 export { OutlineRegion, RegionFrame } from "./OutlineRegion.js";
 export { Table, TableBody, TableCell, TableFoot, TableGroupRow, TableHead, TableHeaderCell, TableRow, } from "./Table.js";
+export { InlineEdit } from "./InlineEdit.js";
 export { TableEditCell } from "./TableEditCell.js";
 export { EmptyState } from "./EmptyState.js";
 export { Step, Steps } from "./Steps.js";
@@ -47,6 +50,7 @@ export { Tabs } from "./Tabs.js";
 export { SegmentedControl } from "./SegmentedControl.js";
 export { FilterGroup } from "./FilterGroup.js";
 export { Checkbox } from "./Checkbox.js";
+export { Switch } from "./Switch.js";
 export { Radio, RadioGroup } from "./RadioGroup.js";
 export { FileDrop } from "./FileDrop.js";
 export { CopyButton } from "./CopyButton.js";

package/dist/labelWords.d.ts

@@ -0,0 +1,12 @@
+import { type ReactNode } from "react";
+/** The label, with its muted description under it when there is one. */
+export declare function Words({ label, description, id, }: {
+    label: ReactNode;
+    description: ReactNode;
+    id: string | undefined;
+}): ReactNode;
+/** The description's id (none without a description) and the control's whole `aria-describedby`. */
+export declare function useDescription(description: ReactNode, describedBy: string | undefined): {
+    descriptionId: string | undefined;
+    describedIds: string;
+};

package/dist/labelWords.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from "react";
+/** The label, with its muted description under it when there is one. */
+export function Words({ label, description, id, }) {
+    if (id === undefined)
+        return label;
+    return (_jsxs("span", { className: "flex flex-col gap-0.5", children: [_jsx("span", { children: label }), _jsx("span", { id: id, className: "text-xs text-slate-500", children: description })] }));
+}
+/** The description's id (none without a description) and the control's whole `aria-describedby`. */
+export function useDescription(description, describedBy) {
+    const generatedId = useId();
+    const descriptionId = description != null && description !== false ? generatedId : undefined;
+    return { descriptionId, describedIds: [describedBy, descriptionId].filter(Boolean).join(" ") };
+}

package/dist/scrollStop.d.ts

@@ -0,0 +1,27 @@
+import { type HTMLAttributes } from "react";
+/** Anything the keyboard can reach on its own. */
+export declare const TABBABLE = ":is(a[href], button, input:not([type=\"hidden\"]), select, textarea, summary, iframe, audio[controls], video[controls], [contenteditable]:not([contenteditable=\"false\"]), [tabindex]):not([disabled], [tabindex=\"-1\"])";
+/**
+ * The keyboard side of a box that scrolls (a `Dialog`'s body, a sticky column): a box that
+ * overflows and holds nothing the keyboard can reach has no way to be scrolled from the keyboard,
+ * so it takes a tab stop (axe's `scrollable-region-focusable`). A box that holds a link, a field or
+ * a button needs none: the keyboard scrolls it by moving focus inside. `attach` is the box's `ref`;
+ * `element` is the box once it is mounted; `stop` is whether it takes the tab stop. Attach it to
+ * nothing and `stop` stays false.
+ */
+export declare function useScrollStop(): {
+    element: HTMLElement | null;
+    attach: (el: HTMLDivElement | null) => void;
+    stop: boolean;
+};
+/**
+ * The props a scroller takes while it holds the tab stop: focusable, ringed and, when the column
+ * has a name, a group of that name so a screen reader says what the stop is. Nothing otherwise.
+ */
+export declare function scrollStopProps(stop: boolean, name?: {
+    label?: string | undefined;
+    labelledBy?: string | undefined;
+}): {
+    props: HTMLAttributes<HTMLDivElement>;
+    ring: string;
+};

package/dist/scrollStop.js

@@ -0,0 +1,68 @@
+import { useEffect, useState } from "react";
+import { focusRing } from "./cx.js";
+/** Anything the keyboard can reach on its own. */
+export const TABBABLE = ':is(a[href], button, input:not([type="hidden"]), select, textarea, summary, iframe, audio[controls], video[controls], [contenteditable]:not([contenteditable="false"]), [tabindex]):not([disabled], [tabindex="-1"])';
+/** Whether something in `scroller` is on screen and reachable by the keyboard. */
+function holdsTabbable(scroller) {
+    for (const el of scroller.querySelectorAll(TABBABLE)) {
+        // A `display: none` summary (a folded column's, from its breakpoint up) is not a tab stop.
+        // jsdom (a consumer's own tests) has no `checkVisibility`; there everything counts.
+        if (typeof el.checkVisibility !== "function" || el.checkVisibility())
+            return true;
+    }
+    return false;
+}
+/**
+ * The keyboard side of a box that scrolls (a `Dialog`'s body, a sticky column): a box that
+ * overflows and holds nothing the keyboard can reach has no way to be scrolled from the keyboard,
+ * so it takes a tab stop (axe's `scrollable-region-focusable`). A box that holds a link, a field or
+ * a button needs none: the keyboard scrolls it by moving focus inside. `attach` is the box's `ref`;
+ * `element` is the box once it is mounted; `stop` is whether it takes the tab stop. Attach it to
+ * nothing and `stop` stays false.
+ */
+export function useScrollStop() {
+    const [element, setElement] = useState(null);
+    const [stop, setStop] = useState(false);
+    useEffect(() => {
+        // jsdom (a consumer's own tests) has no ResizeObserver.
+        if (!element || typeof ResizeObserver === "undefined")
+            return undefined;
+        const measure = () => setStop(element.scrollHeight > element.clientHeight && !holdsTabbable(element));
+        // Each observer reports once when it starts, and again when the box is resized, its content
+        // changes or something in it becomes (un)reachable by the keyboard.
+        const resize = new ResizeObserver(measure);
+        resize.observe(element);
+        for (const child of element.children)
+            resize.observe(child);
+        const change = new MutationObserver(measure);
+        change.observe(element, {
+            childList: true,
+            subtree: true,
+            characterData: true,
+            attributeFilter: ["disabled", "tabindex", "href", "type", "contenteditable", "open"],
+        });
+        return () => {
+            resize.disconnect();
+            change.disconnect();
+        };
+    }, [element]);
+    return { element, attach: setElement, stop: stop && element !== null };
+}
+/**
+ * The props a scroller takes while it holds the tab stop: focusable, ringed and, when the column
+ * has a name, a group of that name so a screen reader says what the stop is. Nothing otherwise.
+ */
+export function scrollStopProps(stop, name = {}) {
+    if (!stop)
+        return { props: {}, ring: "" };
+    const named = name.label !== undefined || name.labelledBy !== undefined;
+    return {
+        props: {
+            tabIndex: 0,
+            ...(named ? { role: "group" } : {}),
+            ...(name.label !== undefined ? { "aria-label": name.label } : {}),
+            ...(name.labelledBy !== undefined ? { "aria-labelledby": name.labelledBy } : {}),
+        },
+        ring: focusRing,
+    };
+}

package/dist/stickyColumn.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A column that stays in view as the page scrolls (`SidebarLayout`'s rail from `md`, `DetailLayout`'s
+ * aside from `lg` when asked). The `<aside>` sticks directly under AppShell's header (`--app-header`,
+ * as `StickyBar` does; 0 outside a shell) and is as tall as its content. A sticky `top` also pushes a
+ * column that starts above it down, so it is exactly the header and no gap: a gap would move a rail
+ * rendered at the top of its box. Inside it the scroller is capped at the viewport less the header
+ * and 2rem (the room the Container's `py-8` leaves at the page's end, so the column is never pushed
+ * up under the header there), so a column taller than that scrolls itself and its end stays
+ * reachable. `overflow` clips, which would cut a keyboard focus ring (an outline 4px out) at the
+ * scroller's edges, so it is padded 4px (`p-1`) and pulled back out by the same (`-m-1`): the ring
+ * has room and the column stays on the page's edges. Each variant is written out whole, so Tailwind
+ * sees every class.
+ */
+export declare const STICKY_ASIDE_MD = "md:sticky md:top-[var(--app-header,0px)] md:self-start";
+export declare const STICKY_SCROLL_MD = "md:-m-1 md:max-h-[calc(100dvh-var(--app-header,0px)-2rem)] md:overflow-y-auto md:p-1";
+export declare const STICKY_ASIDE_LG = "lg:sticky lg:top-[var(--app-header,0px)] lg:self-start";
+export declare const STICKY_SCROLL_LG = "lg:-m-1 lg:max-h-[calc(100dvh-var(--app-header,0px)-2rem)] lg:overflow-y-auto lg:p-1";

package/dist/stickyColumn.js

@@ -0,0 +1,17 @@
+/**
+ * A column that stays in view as the page scrolls (`SidebarLayout`'s rail from `md`, `DetailLayout`'s
+ * aside from `lg` when asked). The `<aside>` sticks directly under AppShell's header (`--app-header`,
+ * as `StickyBar` does; 0 outside a shell) and is as tall as its content. A sticky `top` also pushes a
+ * column that starts above it down, so it is exactly the header and no gap: a gap would move a rail
+ * rendered at the top of its box. Inside it the scroller is capped at the viewport less the header
+ * and 2rem (the room the Container's `py-8` leaves at the page's end, so the column is never pushed
+ * up under the header there), so a column taller than that scrolls itself and its end stays
+ * reachable. `overflow` clips, which would cut a keyboard focus ring (an outline 4px out) at the
+ * scroller's edges, so it is padded 4px (`p-1`) and pulled back out by the same (`-m-1`): the ring
+ * has room and the column stays on the page's edges. Each variant is written out whole, so Tailwind
+ * sees every class.
+ */
+export const STICKY_ASIDE_MD = "md:sticky md:top-[var(--app-header,0px)] md:self-start";
+export const STICKY_SCROLL_MD = "md:-m-1 md:max-h-[calc(100dvh-var(--app-header,0px)-2rem)] md:overflow-y-auto md:p-1";
+export const STICKY_ASIDE_LG = "lg:sticky lg:top-[var(--app-header,0px)] lg:self-start";
+export const STICKY_SCROLL_LG = "lg:-m-1 lg:max-h-[calc(100dvh-var(--app-header,0px)-2rem)] lg:overflow-y-auto lg:p-1";

package/package.json

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