@scalewing/react 1.46.0 → 1.48.0

package/dist/components/site-header/use-menu-dismiss.js

@@ -0,0 +1,62 @@
+import { useEffect } from 'react';
+import { breakpointQuery } from '../../css/breakpoints.js';
+/** From here the bar shows its row of destinations and hides the menu. */
+const wideQuery = breakpointQuery('from', 'lg');
+/**
+ * What script adds to the menu, a native `details` that opens and closes
+ * without it: Escape closes it and puts focus back on its button; choosing
+ * a link in it, focus leaving it, a press outside it, or the window
+ * widening to the row of destinations closes it. Nothing traps focus.
+ */
+export function useMenuDismiss(menuRef) {
+    useEffect(() => {
+        const menu = menuRef.current;
+        if (!menu)
+            return;
+        const close = () => {
+            menu.open = false;
+        };
+        const onKeyDown = (event) => {
+            if (event.key !== 'Escape' || !menu.open)
+                return;
+            event.preventDefault();
+            close();
+            menu.querySelector('summary')?.focus();
+        };
+        const onClick = (event) => {
+            if (event.target instanceof Element && event.target.closest('a'))
+                close();
+        };
+        const onFocusOut = (event) => {
+            const next = event.relatedTarget;
+            if (next instanceof Node && menu.contains(next))
+                return;
+            if (next !== null)
+                close();
+        };
+        const onPointerDown = (event) => {
+            if (event.target instanceof Node && menu.contains(event.target))
+                return;
+            close();
+        };
+        const wide = typeof window.matchMedia === 'function'
+            ? window.matchMedia(wideQuery)
+            : undefined;
+        const onWiden = () => {
+            if (wide?.matches)
+                close();
+        };
+        menu.addEventListener('keydown', onKeyDown);
+        menu.addEventListener('click', onClick);
+        menu.addEventListener('focusout', onFocusOut);
+        document.addEventListener('pointerdown', onPointerDown);
+        wide?.addEventListener('change', onWiden);
+        return () => {
+            menu.removeEventListener('keydown', onKeyDown);
+            menu.removeEventListener('click', onClick);
+            menu.removeEventListener('focusout', onFocusOut);
+            document.removeEventListener('pointerdown', onPointerDown);
+            wide?.removeEventListener('change', onWiden);
+        };
+    }, [menuRef]);
+}

package/dist/components/site-header/validate.d.ts

@@ -0,0 +1,7 @@
+import { type SiteHeaderProps } from './types.js';
+/**
+ * Fails closed on the header's words and destinations: no items, blank or
+ * repeated ids, blank labels or hrefs, and a blank navigation name or menu
+ * button name.
+ */
+export declare function assertSiteHeaderProps({ items, labels, navLabel, }: Pick<SiteHeaderProps, 'items' | 'labels' | 'navLabel'>): void;

package/dist/components/site-header/validate.js

@@ -0,0 +1,17 @@
+import { assertNavItems } from '../nav-items.js';
+/**
+ * Fails closed on the header's words and destinations: no items, blank or
+ * repeated ids, blank labels or hrefs, and a blank navigation name or menu
+ * button name.
+ */
+export function assertSiteHeaderProps({ items, labels, navLabel, }) {
+    if (items.length === 0)
+        throw new RangeError('SiteHeader needs at least one item');
+    assertNavItems('SiteHeader', items);
+    if (items.some((item) => !item.href.trim()))
+        throw new RangeError('SiteHeader items need nonempty hrefs');
+    if (!navLabel.trim())
+        throw new RangeError('SiteHeader needs a nonempty navLabel');
+    if (!labels.openMenu.trim() || !labels.closeMenu.trim())
+        throw new RangeError('SiteHeader labels need nonempty openMenu and closeMenu');
+}

package/dist/components/use-element-height.d.ts

@@ -0,0 +1,10 @@
+import { type RefObject } from 'react';
+/**
+ * Follows the height of an element's border box, in CSS pixels: on
+ * mount, before the first paint, and whenever its box changes size. It is
+ * `null` before that, on the server, while `enabled` is false and while the
+ * element draws no box (`display: none`), so a caller can fall back to a
+ * value of its own. A browser with no ResizeObserver measures on window
+ * resizes instead.
+ */
+export declare function useElementHeight(ref: RefObject<HTMLElement | null>, enabled?: boolean): number | null;

package/dist/components/use-element-height.js

@@ -0,0 +1,35 @@
+'use client';
+import { useLayoutEffect, useState } from 'react';
+/**
+ * Follows the height of an element's border box, in CSS pixels: on
+ * mount, before the first paint, and whenever its box changes size. It is
+ * `null` before that, on the server, while `enabled` is false and while the
+ * element draws no box (`display: none`), so a caller can fall back to a
+ * value of its own. A browser with no ResizeObserver measures on window
+ * resizes instead.
+ */
+export function useElementHeight(ref, enabled = true) {
+    const [height, setHeight] = useState(null);
+    useLayoutEffect(() => {
+        const box = ref.current;
+        if (!box || !enabled) {
+            setHeight(null);
+            return;
+        }
+        function measure() {
+            if (!box)
+                return;
+            const next = box.getBoundingClientRect().height;
+            setHeight(next > 0 ? next : null);
+        }
+        measure();
+        if (typeof ResizeObserver === 'undefined') {
+            window.addEventListener('resize', measure);
+            return () => window.removeEventListener('resize', measure);
+        }
+        const observer = new ResizeObserver(measure);
+        observer.observe(box);
+        return () => observer.disconnect();
+    }, [ref, enabled]);
+    return height;
+}

package/dist/context-switcher.test-support.d.ts

@@ -0,0 +1,9 @@
+import { type RenderResult } from '@testing-library/react';
+import { type Mock } from 'vitest';
+import { type ContextSwitcherGroup, type ContextSwitcherProps } from './components/ContextSwitcher.js';
+/** Field stations: a bare group, then a labelled one with badges and counts. */
+export declare const stations: ContextSwitcherGroup[];
+/** The switcher with its required props, and any prop overridden. */
+export declare function renderSwitcher(props?: Partial<ContextSwitcherProps>): RenderResult & {
+    onSelect: Mock;
+};

package/dist/context-switcher.test-support.js

@@ -0,0 +1,41 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { render } from '@testing-library/react';
+import { vi } from 'vitest';
+import { ContextSwitcher, } from './components/ContextSwitcher.js';
+/** Field stations: a bare group, then a labelled one with badges and counts. */
+export const stations = [
+    {
+        id: 'home',
+        options: [
+            {
+                id: 'all',
+                label: 'All stations',
+                icon: _jsx("svg", { "data-glyph": "all" }),
+                count: 7,
+                countLabel: '7 need you',
+                countTone: 'warning',
+            },
+        ],
+    },
+    {
+        id: 'mine',
+        label: 'Stations you run',
+        options: [
+            {
+                id: 'heron',
+                label: 'Heron Marsh',
+                detail: 'Warden',
+                badge: { label: 'Live', tone: 'success' },
+            },
+            { id: 'pine', label: 'Pine Ridge', detail: 'Ranger' },
+            { id: 'bittern', label: 'Bittern Fen', count: 2 },
+            { id: 'bay', label: 'Bayside Dunes', detail: 'Árbol team' },
+        ],
+    },
+];
+/** The switcher with its required props, and any prop overridden. */
+export function renderSwitcher(props = {}) {
+    const onSelect = vi.fn();
+    const view = render(_jsx(ContextSwitcher, { currentId: "heron", groups: stations, label: "Station", onSelect: onSelect, trigger: "Heron Marsh", ...props }));
+    return { ...view, onSelect };
+}

package/dist/css/css-app-shell-drawer.d.ts

@@ -0,0 +1,2 @@
+export declare function cssAppShellDrawerClasses(): string;
+export declare function appShellDrawerClassCatalog(): string[];

package/dist/css/css-app-shell-drawer.js

@@ -0,0 +1,91 @@
+import { iconButtonRules } from './css-icon-button.js';
+/* The drawer's width, a named geometry of this frame; a phone keeps a strip of backdrop. */
+const drawerWidth = '20rem';
+const drawer = '.sw-app-shell-drawer';
+/*
+ * AppShell's menu below `lg`: a modal `dialog` on the top layer, docked to
+ * the inline start (the right in right-to-left) at the viewport's full
+ * height on the solid surface, a hairline at its inline end, clearing the
+ * safe areas, a space-8 strip of backdrop left in view on a phone. It
+ * slides in from its edge unless reduced motion is asked for. Its column
+ * is the top row (the close button where the menu button was, then the
+ * header), the nav, which alone scrolls, and the footer. The backdrop is
+ * Dialog's.
+ */
+export function cssAppShellDrawerClasses() {
+    return `${drawer} {
+  background: var(--sw-color-surface);
+  border: 0;
+  border-inline-end: 1px solid var(--sw-color-border);
+  box-sizing: border-box;
+  color: var(--sw-color-text);
+  height: 100%;
+  inset-block: 0;
+  inset-inline: 0 auto;
+  margin: 0;
+  max-height: none;
+  max-width: calc(100% - var(--sw-space-8));
+  overflow: hidden;
+  padding: env(safe-area-inset-top, 0px) 0 env(safe-area-inset-bottom, 0px);
+  padding-inline-start: env(safe-area-inset-left, 0px);
+  width: ${drawerWidth};
+}
+
+${drawer}:dir(rtl) {
+  padding-inline-start: env(safe-area-inset-right, 0px);
+}
+
+${drawer}[open] {
+  animation: sw-app-shell-drawer-in var(--sw-motion-default) var(--sw-motion-easing);
+  display: flex;
+  flex-direction: column;
+}
+
+${drawer}[open]:dir(rtl) {
+  animation-name: sw-app-shell-drawer-in-rtl;
+}
+
+@keyframes sw-app-shell-drawer-in {
+  from { translate: -100% 0; }
+}
+
+@keyframes sw-app-shell-drawer-in-rtl {
+  from { translate: 100% 0; }
+}
+
+${drawer}::backdrop {
+  background: color-mix(in srgb, var(--sw-color-text) 28%, transparent);
+}
+
+.sw-app-shell-drawer-top {
+  align-items: center;
+  display: flex;
+  flex: none;
+  gap: var(--sw-space-2);
+  padding: var(--sw-space-3) var(--sw-space-3) 0;
+}
+
+.sw-app-shell-drawer-top .sw-app-shell-header {
+  flex: 1 1 auto;
+  min-width: 0;
+  padding: 0;
+}
+
+${iconButtonRules('sw-app-shell-close')}
+
+@media (prefers-reduced-motion: reduce) {
+  ${drawer}[open],
+  ${drawer}[open]:dir(rtl) { animation: none; }
+}
+
+@media (forced-colors: active) {
+  ${drawer} { border-inline-end-color: CanvasText; }
+}`;
+}
+export function appShellDrawerClassCatalog() {
+    return [
+        'sw-app-shell-drawer',
+        'sw-app-shell-drawer-top',
+        'sw-app-shell-close',
+    ];
+}

package/dist/css/css-app-shell-nav.d.ts

@@ -0,0 +1,3 @@
+export declare function cssAppShellNavClasses(): string;
+export declare function cssAppShellRailNavRules(indent: string): string;
+export declare function appShellNavClassCatalog(): string[];

package/dist/css/css-app-shell-nav.js

@@ -0,0 +1,167 @@
+import { typographyVariants } from '@scalewing/tokens';
+import { visuallyHiddenDeclarations } from './css-utilities.js';
+import { coarsePointerQuery, touchTarget } from './touch-target.js';
+const caption = typographyVariants.caption;
+const label = typographyVariants.label;
+/*
+ * The shell's destinations, in the full sidebar and the drawer alike: label
+ * size in the text colour at weight 500, the glyph before the label and the
+ * count pill (the shared rule, `css-count-pill.ts`) at the row's end. The
+ * current one takes the quiet muted fill in the text colour at the label
+ * weight, as SectionNav \`filled\` marks it; hover a lighter fill. Each is
+ * the sm control and the 44 px target on a coarse pointer. A 2 px
+ * transparent border keeps room for forced colours, where the current
+ * link's turns Highlight. A group's label is a muted caption at weight 600
+ * (sentence case, never uppercase). The link rules start at the canvas
+ * (\`[data-theme]\`) to outrank its accent links.
+ */
+export function cssAppShellNavClasses() {
+    return `.sw-app-shell-nav {
+  box-sizing: border-box;
+  display: flex;
+  flex: 1 1 auto;
+  flex-direction: column;
+  gap: var(--sw-space-4);
+  min-height: 0;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  padding: var(--sw-space-2) var(--sw-space-3);
+}
+
+.sw-app-shell-group {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sw-space-1);
+}
+
+.sw-app-shell-group-label {
+  color: var(--sw-color-muted);
+  font-family: var(--sw-font-sans);
+  font-size: ${caption.fontSize}px;
+  font-weight: 600;
+  letter-spacing: ${caption.letterSpacing}px;
+  line-height: ${caption.lineHeight}px;
+  margin: 0;
+  padding-inline: var(--sw-space-2);
+}
+
+.sw-app-shell-list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sw-space-1);
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.sw-app-shell-item > .sw-tooltip-anchor {
+  display: flex;
+}
+
+[data-theme] .sw-app-shell-link {
+  align-items: center;
+  border: 2px solid transparent;
+  border-radius: var(--sw-radius-sm);
+  box-sizing: border-box;
+  color: var(--sw-color-text);
+  display: flex;
+  flex: 1 1 auto;
+  font-family: var(--sw-font-sans);
+  font-size: ${label.fontSize}px;
+  font-weight: 500;
+  gap: var(--sw-space-3);
+  letter-spacing: ${label.letterSpacing}px;
+  line-height: ${label.lineHeight}px;
+  min-height: var(--sw-control-sm-min-height);
+  padding: var(--sw-space-1) var(--sw-space-2);
+  text-decoration: none;
+}
+
+[data-theme] .sw-app-shell-link:hover {
+  background: color-mix(in srgb, var(--sw-color-muted) 12%, transparent);
+}
+
+[data-theme] .sw-app-shell-link:focus-visible {
+  outline: var(--sw-focus-ring-width) solid var(--sw-color-accent);
+  outline-offset: calc(-1 * var(--sw-focus-ring-width));
+}
+
+[data-theme] .sw-app-shell-link[aria-current] {
+  background: color-mix(in srgb, var(--sw-color-muted) 18%, transparent);
+  font-weight: ${label.fontWeight};
+}
+
+.sw-app-shell-icon {
+  display: inline-flex;
+  flex: none;
+}
+
+.sw-app-shell-label {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
+.sw-app-shell-count {
+  flex: none;
+}
+
+@media ${coarsePointerQuery} {
+  [data-theme] .sw-app-shell-link { min-height: ${touchTarget}; }
+}
+
+@media (forced-colors: active) {
+  [data-theme] .sw-app-shell-link { color: LinkText; }
+  [data-theme] .sw-app-shell-link[aria-current] { border-color: Highlight; color: CanvasText; }
+}`;
+}
+/*
+ * The rail (from \`lg\` to 75rem, inside the sidebar's media queries): each
+ * link the 44 px target holding its glyph alone, the label visually hidden
+ * but still its name, the count pill at the link's top end corner. A
+ * group's label is hidden too (it still names its list) and every group
+ * after the first starts under a hairline.
+ */
+export function cssAppShellRailNavRules(indent) {
+    const rules = `.sw-app-shell-sidebar .sw-app-shell-label,
+.sw-app-shell-sidebar .sw-app-shell-group-label { ${visuallyHiddenDeclarations} }
+
+.sw-app-shell-sidebar .sw-app-shell-nav {
+  gap: var(--sw-space-2);
+}
+
+.sw-app-shell-sidebar .sw-app-shell-group + .sw-app-shell-group {
+  border-top: 1px solid var(--sw-color-border);
+  padding-top: var(--sw-space-2);
+}
+
+[data-theme] .sw-app-shell-sidebar .sw-app-shell-link {
+  justify-content: center;
+  min-height: ${touchTarget};
+  padding: 0;
+  position: relative;
+}
+
+.sw-app-shell-sidebar .sw-app-shell-count {
+  inset-block-start: 0;
+  inset-inline-end: 0;
+  position: absolute;
+}`;
+    return rules
+        .split('\n')
+        .map((line) => (line ? `${indent}${line}` : line))
+        .join('\n');
+}
+export function appShellNavClassCatalog() {
+    return [
+        'sw-app-shell-nav',
+        'sw-app-shell-group',
+        'sw-app-shell-group-label',
+        'sw-app-shell-list',
+        'sw-app-shell-item',
+        'sw-app-shell-link',
+        'sw-app-shell-icon',
+        'sw-app-shell-label',
+        // sw-app-shell-count is the shared pill's (css-count-pill.ts).
+    ];
+}

package/dist/css/css-app-shell-page-bar.d.ts

@@ -0,0 +1,3 @@
+export declare const appShellBarHeightVariable = "--sw-app-shell-bar-height";
+export declare function cssAppShellPageBarClasses(): string;
+export declare function appShellPageBarClassCatalog(): string[];

package/dist/css/css-app-shell-page-bar.js

@@ -0,0 +1,81 @@
+import { breakpointQuery } from './breakpoints.js';
+import { zIndex } from './stacking.js';
+import { coarsePointerQuery, touchTarget } from './touch-target.js';
+/*
+ * The compact bar's measured height, set on `.sw-app-shell` by the
+ * component while it draws a page bar, so the page bar sticks right under
+ * the bar whatever its end controls make it.
+ */
+export const appShellBarHeightVariable = '--sw-app-shell-bar-height';
+/*
+ * The bar's usual height before it is measured (and without script): the
+ * sm menu button, or the touch target on a coarse pointer, inside the
+ * bar's space-2 padding, and its hairline.
+ */
+function barHeightFallback(control) {
+    return `calc(${control} + 2 * var(--sw-space-2) + 1px)`;
+}
+const fromLg = breakpointQuery('from', 'lg');
+/*
+ * `pageBar`: a band at the top of `main` on every layout, the solid
+ * surface with a hairline under it and the page's inline padding (space-4,
+ * space-6 from `lg`), its children a wrapping row with space between them.
+ * Sticky on the top chrome's layer: under the compact bar below `lg`, at
+ * the window's top from `lg`, where the bar is gone. Reduce Transparency
+ * needs nothing (it is already solid); forced colours keep the hairline.
+ */
+function pageBarRules() {
+    return `.sw-app-shell-page-bar {
+  align-items: center;
+  background: var(--sw-color-surface);
+  border-bottom: 1px solid var(--sw-color-border);
+  box-sizing: border-box;
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--sw-space-2) var(--sw-space-3);
+  justify-content: space-between;
+  padding: var(--sw-space-2) var(--sw-space-4);
+  position: sticky;
+  top: var(${appShellBarHeightVariable}, ${barHeightFallback('var(--sw-control-sm-min-height)')});
+  ${zIndex('topChrome')}
+}
+
+@media ${coarsePointerQuery} {
+  .sw-app-shell-page-bar {
+    top: var(${appShellBarHeightVariable}, ${barHeightFallback(touchTarget)});
+  }
+}
+
+@media ${fromLg} {
+  .sw-app-shell-page-bar {
+    padding-inline: var(--sw-space-6);
+    top: 0;
+  }
+}`;
+}
+/*
+ * `menuCount`: the shared count pill (`sw-app-shell-count`, its tones
+ * included) on the menu button's top end corner, over the glyph's edge as
+ * on a rail glyph, mirrored in right-to-left.
+ */
+function menuCountRules() {
+    return `.sw-app-shell-menu {
+  position: relative;
+}
+
+.sw-app-shell-menu .sw-app-shell-count {
+  inset-block-start: calc(-1 * var(--sw-space-1));
+  inset-inline-end: calc(-1 * var(--sw-space-1));
+  pointer-events: none;
+  position: absolute;
+}`;
+}
+/* AppShell's page bar and the menu button's count (see components/AppShell.tsx). */
+export function cssAppShellPageBarClasses() {
+    return `${pageBarRules()}
+
+${menuCountRules()}`;
+}
+export function appShellPageBarClassCatalog() {
+    return ['sw-app-shell-page-bar'];
+}

package/dist/css/css-app-shell.d.ts

@@ -0,0 +1,4 @@
+/** From this width up AppShell draws its full sidebar; script reads it too. */
+export declare const appShellWideQuery = "(min-width: 75rem)";
+export declare function cssAppShellClasses(): string;
+export declare function appShellClassCatalog(): string[];