@hackcove/ui-react 0.9.1 → 0.9.2

package/README.md

@@ -1,7 +1,7 @@
 # @hackcove/ui-react
 
 Hack Cove React components, written against Tailwind v4 utilities. They carry no theme: pair them
-with a `@hackcove/theme-*` package such as `@hackcove/theme-catppuccin-mocha` and put its scope
+with a theme from `@hackcove/themes`, such as `@hackcove/themes/catppuccin-mocha.css`, and put its scope
 class on `<html>` (`.dark` for Mocha). With no theme they render in Tailwind's own default colours,
 a plain light look; it works, but it is not a look Hack Cove designs or checks.
 
@@ -253,6 +253,9 @@ except the last four.
   `children` is the list, replaced by `empty` when `isEmpty`.
 - **`DetailLayout`**: use this when a page is one thing with facts beside it. `children` take two
   thirds from `lg` and `aside` one third; below `lg` the aside stacks under the main column.
+  `stickyAside` (off by default, since an aside of ordinary cards may be taller than the screen)
+  keeps the aside in view from `lg` as a long page scrolls: it sticks under the shell's header and
+  scrolls itself when it is taller than the room left.
 - **`FormLayout`**: use this for a create or edit page. A `max-w-3xl` `<form>` that starts at the
   Container's left edge (it is not re-centred, so the title does not jump), with an `actions` row at
   the end. Other props (`onSubmit`, `action`) go on the `<form>`.
@@ -271,8 +274,10 @@ except the last four.
   plain `<AppShell>`, no `bleed`: it sits in the Container like every other layout, so the rail
   starts at the header logo's x and the canvas ends at the header's right edge. The rail has no fill
   and no border (pill `Tabs` with `orientation="vertical"` is its content); from `md` it is `md:w-56` beside
-  the canvas, and below `md` it stacks above it. A long rail sets `railLabel`: below `md` the rail
-  then folds, closed, behind a disclosure of that name, so a phone shows the page first.
+  the canvas, and below `md` it stacks above it. From `md` the rail also stays in view under the
+  shell's header as a long page scrolls (always, with or without `railLabel`); a rail taller than
+  the screen scrolls itself, so its last link is reachable. A long rail sets `railLabel`: below `md`
+  the rail then folds, closed, behind a disclosure of that name, so a phone shows the page first.
 - **`FullBleedLayout`**: use this for a viewer that needs the whole width. Render it in
   `<AppShell bleed>`; `children` fill the width, and an optional `panel` takes `lg:w-72` on the
   right and stacks below under `lg`. It adds no padding, so a viewer fills the width; set `padded`

package/dist/PageLayouts.d.ts

@@ -12,10 +12,22 @@ export declare function ListLayout({ filters, empty, isEmpty, children, breadcru
     isEmpty?: boolean;
     children?: ReactNode;
 } & Passthrough): ReactElement;
-/** A detail page: header, then `children` (two thirds from `lg`) beside `aside` (one third), which stacks below on a smaller screen. */
-export declare function DetailLayout({ aside, children, breadcrumbs, title, subtitle, actions, tabs, ...rest }: PageHeaderProps & {
+/**
+ * A detail page: header, then `children` (two thirds from `lg`) beside `aside` (one third), which
+ * stacks below on a smaller screen. `stickyAside` keeps the aside in view from `lg` as a long page
+ * scrolls: it sticks under AppShell's header and, if it is taller than the room left, scrolls
+ * itself so its end stays reachable.
+ */
+export declare function DetailLayout({ aside, stickyAside, children, breadcrumbs, title, subtitle, actions, tabs, ...rest }: PageHeaderProps & {
     /** The side column: one third from `lg`, below `children` on a smaller screen. */
     aside: ReactNode;
+    /**
+     * From `lg`, keeps the aside in view under the header as the page scrolls; an aside taller than
+     * the screen scrolls inside itself. Off by default, since an aside of ordinary cards may be
+     * taller than the screen. Below `lg` the aside stacks as ever.
+     * @default false
+     */
+    stickyAside?: boolean | undefined;
     children: ReactNode;
 } & Passthrough): ReactElement;
 /** A form page: header (no header `actions`), then a `max-w-3xl` column that starts at the Container's left edge (it is not re-centred), with an `actions` row at the end. Other props go on the `<form>`. */
@@ -97,23 +109,6 @@ type CardGridProps = ({
  * screen reader: the grid is a `<ul>` and each child is wrapped in an `<li>`, still stretched.
  */
 export declare function CardGrid({ columns, minWidth, align, as: Tag, children, ...rest }: CardGridProps): ReactElement;
-/**
- * A `rail` of links beside the `children` canvas, in the Container the shell already gives every
- * page (a plain `<AppShell>`, no `bleed`): the rail starts at the header logo's x and the canvas
- * ends at the header's right edge. The rail has no background and no border, so it is a list of
- * links on the page; a `Tabs variant="pill" orientation="vertical"` is its content. From `md` it is `w-56` with
- * the canvas filling the rest; below `md` it stacks above the canvas. A long rail sets `railLabel`:
- * below `md` it then folds behind a disclosure of that name, closed, so the page comes first on a
- * phone, and from `md` it is the same rail. Upgrading from 0.2: the rail no longer has a fill, a
- * border or a fixed height, and it no longer sits beside the canvas on a phone.
- */
-export declare function SidebarLayout({ rail, railLabel, children, ...rest }: {
-    /** The links beside the canvas, usually a `Tabs variant="pill" orientation="vertical"`. */
-    rail: ReactNode;
-    /** Folds the rail behind a disclosure with this name below `md` (a long rail). Left out, the rail is always open. */
-    railLabel?: string | undefined;
-    children: ReactNode;
-} & Passthrough): ReactElement;
 /**
  * Edge-to-edge `children` with an optional right `panel` (`lg:w-72`) that stacks below on a smaller
  * screen. Render it in `<AppShell bleed>`. It deliberately breaks the shared left edge: a viewer

package/dist/PageLayouts.js

@@ -1,9 +1,10 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Children, isValidElement, } from "react";
 import { Card } from "./Card.js";
-import { cx, focusRing } from "./cx.js";
+import { cx } from "./cx.js";
 import { PageHeader, PageHeaderContent } from "./PageHeader.js";
 import { STACK_WIDTH, Stack } from "./Stack.js";
+import { STICKY_ASIDE_LG, STICKY_SCROLL_LG } from "./stickyColumn.js";
 import { StickyBar } from "./StickyBar.js";
 // Compositions of the layout foundation. None sets a page width or outer padding of its own; the
 // ones that narrow their content do it inside the Container they are rendered in.
@@ -11,9 +12,14 @@ import { StickyBar } from "./StickyBar.js";
 export function ListLayout({ filters, empty, isEmpty = false, children, breadcrumbs, title, subtitle, actions, tabs, ...rest }) {
     return (_jsxs(_Fragment, { children: [_jsx(PageHeader, { breadcrumbs: breadcrumbs, title: title, subtitle: subtitle, actions: actions, tabs: tabs }), _jsxs(Stack, { ...rest, children: [filters, isEmpty ? empty : children] })] }));
 }
-/** A detail page: header, then `children` (two thirds from `lg`) beside `aside` (one third), which stacks below on a smaller screen. */
-export function DetailLayout({ aside, children, breadcrumbs, title, subtitle, actions, tabs, ...rest }) {
-    return (_jsxs(_Fragment, { children: [_jsx(PageHeader, { breadcrumbs: breadcrumbs, title: title, subtitle: subtitle, actions: actions, tabs: tabs }), _jsxs("div", { ...rest, className: "grid gap-6 lg:grid-cols-3", children: [_jsx("div", { className: "min-w-0 lg:col-span-2", children: _jsx(Stack, { children: children }) }), _jsx("aside", { className: "min-w-0", children: _jsx(Stack, { children: aside }) })] })] }));
+/**
+ * A detail page: header, then `children` (two thirds from `lg`) beside `aside` (one third), which
+ * stacks below on a smaller screen. `stickyAside` keeps the aside in view from `lg` as a long page
+ * scrolls: it sticks under AppShell's header and, if it is taller than the room left, scrolls
+ * itself so its end stays reachable.
+ */
+export function DetailLayout({ aside, stickyAside = false, children, breadcrumbs, title, subtitle, actions, tabs, ...rest }) {
+    return (_jsxs(_Fragment, { children: [_jsx(PageHeader, { breadcrumbs: breadcrumbs, title: title, subtitle: subtitle, actions: actions, tabs: tabs }), _jsxs("div", { ...rest, className: "grid gap-6 lg:grid-cols-3", children: [_jsx("div", { className: "min-w-0 lg:col-span-2", children: _jsx(Stack, { children: children }) }), _jsx("aside", { className: cx("min-w-0", stickyAside && STICKY_ASIDE_LG), children: _jsx("div", { className: stickyAside ? STICKY_SCROLL_LG : undefined, children: _jsx(Stack, { children: aside }) }) })] })] }));
 }
 /** A form page: header (no header `actions`), then a `max-w-3xl` column that starts at the Container's left edge (it is not re-centred), with an `actions` row at the end. Other props go on the `<form>`. */
 export function FormLayout({ actions, children, breadcrumbs, title, subtitle, tabs, ...form }) {
@@ -66,19 +72,6 @@ export function CardGrid({ columns = 3, minWidth = "md", align = "stretch", as:
             ? Children.toArray(children).map((child, index) => (_jsx("li", { className: "grid", children: child }, isValidElement(child) ? child.key : index)))
             : children }));
 }
-/**
- * A `rail` of links beside the `children` canvas, in the Container the shell already gives every
- * page (a plain `<AppShell>`, no `bleed`): the rail starts at the header logo's x and the canvas
- * ends at the header's right edge. The rail has no background and no border, so it is a list of
- * links on the page; a `Tabs variant="pill" orientation="vertical"` is its content. From `md` it is `w-56` with
- * the canvas filling the rest; below `md` it stacks above the canvas. A long rail sets `railLabel`:
- * below `md` it then folds behind a disclosure of that name, closed, so the page comes first on a
- * phone, and from `md` it is the same rail. Upgrading from 0.2: the rail no longer has a fill, a
- * border or a fixed height, and it no longer sits beside the canvas on a phone.
- */
-export function SidebarLayout({ rail, railLabel, children, ...rest }) {
-    return (_jsxs("div", { ...rest, className: "flex flex-col gap-8 md:flex-row md:gap-10", children: [_jsx("aside", { className: "w-full shrink-0 md:w-56", children: railLabel === undefined ? (rail) : (_jsxs("details", { className: "group md:[&::details-content]:[content-visibility:visible]", 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 md:hidden [&::-webkit-details-marker]:hidden", focusRing), children: [railLabel, _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: "mt-2 md:mt-0", children: rail })] })) }), _jsx("div", { className: "min-w-0 flex-1", children: children })] }));
-}
 /**
  * Edge-to-edge `children` with an optional right `panel` (`lg:w-72`) that stacks below on a smaller
  * screen. Render it in `<AppShell bleed>`. It deliberately breaks the shared left edge: a viewer

package/dist/SidebarLayout.d.ts

@@ -0,0 +1,21 @@
+import type { ReactElement, ReactNode } from "react";
+import type { Passthrough } from "./props.js";
+/**
+ * A `rail` of links beside the `children` canvas, in the Container the shell already gives every
+ * page (a plain `<AppShell>`, no `bleed`): the rail starts at the header logo's x and the canvas
+ * ends at the header's right edge. The rail has no background and no border, so it is a list of
+ * links on the page; a `Tabs variant="pill" orientation="vertical"` is its content. From `md` it is `w-56` with
+ * the canvas filling the rest, and it stays in view under the shell's header as a long page scrolls;
+ * a rail taller than the screen scrolls itself, so its last link is reachable. Below `md` it stacks
+ * above the canvas and nothing sticks. A long rail sets `railLabel`:
+ * below `md` it then folds behind a disclosure of that name, closed, so the page comes first on a
+ * phone, and from `md` it is the same rail. Upgrading from 0.2: the rail no longer has a fill, a
+ * border or a fixed height, and it no longer sits beside the canvas on a phone.
+ */
+export declare function SidebarLayout({ rail, railLabel, children, ...rest }: {
+    /** The links beside the canvas, usually a `Tabs variant="pill" orientation="vertical"`. */
+    rail: ReactNode;
+    /** Folds the rail behind a disclosure with this name below `md` (a long rail). Left out, the rail is always open. */
+    railLabel?: string | undefined;
+    children: ReactNode;
+} & Passthrough): ReactElement;

package/dist/SidebarLayout.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx, focusRing } from "./cx.js";
+import { STICKY_ASIDE_MD, STICKY_SCROLL_MD } from "./stickyColumn.js";
+/**
+ * A `rail` of links beside the `children` canvas, in the Container the shell already gives every
+ * page (a plain `<AppShell>`, no `bleed`): the rail starts at the header logo's x and the canvas
+ * ends at the header's right edge. The rail has no background and no border, so it is a list of
+ * links on the page; a `Tabs variant="pill" orientation="vertical"` is its content. From `md` it is `w-56` with
+ * the canvas filling the rest, and it stays in view under the shell's header as a long page scrolls;
+ * a rail taller than the screen scrolls itself, so its last link is reachable. Below `md` it stacks
+ * above the canvas and nothing sticks. A long rail sets `railLabel`:
+ * below `md` it then folds behind a disclosure of that name, closed, so the page comes first on a
+ * phone, and from `md` it is the same rail. Upgrading from 0.2: the rail no longer has a fill, a
+ * border or a fixed height, and it no longer sits beside the canvas on a phone.
+ */
+export function SidebarLayout({ rail, railLabel, children, ...rest }) {
+    return (_jsxs("div", { ...rest, className: "flex flex-col gap-8 md:flex-row md:gap-10", children: [_jsx("aside", { className: cx("w-full shrink-0 md:w-56", STICKY_ASIDE_MD), children: _jsx("div", { className: STICKY_SCROLL_MD, children: railLabel === undefined ? (rail) : (_jsxs("details", { className: "group md:[&::details-content]:[content-visibility:visible]", 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 md:hidden [&::-webkit-details-marker]:hidden", focusRing), children: [railLabel, _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: "mt-2 md:mt-0", children: rail })] })) }) }), _jsx("div", { className: "min-w-0 flex-1", children: children })] }));
+}

package/dist/index.d.ts

@@ -10,7 +10,8 @@ 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 { 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";

package/dist/index.js

@@ -10,7 +10,8 @@ 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 { StickyBar } from "./StickyBar.js";
 export { ErrorPage, Forbidden, Maintenance, NotFound, Offline } from "./StatusPages.js";
 export { Cluster, ClusterGrow, } from "./Cluster.js";

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.9.2",
+  "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",