shelving 1.291.1 → 1.292.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.291.1",
+	"version": "1.292.1",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",

package/ui/transition/HorizontalTransition.css

@@ -1,6 +1,11 @@
-@layer base {
+@import url("../style/layers.css");
+@import url("../style/Duration.module.css");
+
+/* Global CSS, not a CSS module — see `Transition.css` for why. */
+@layer defaults {
 	:root {
-		--horizontal-transition-size: 25vw;
+		/* A percentage is of the snapshot's own size, so the old and new content sit edge to edge and never overlap. */
+		--horizontal-transition-size: 100%;
 		--horizontal-transition-duration: var(--duration-normal);
 	}
 }
@@ -53,6 +58,12 @@
 	}
 }
 
+/* Clip the slide to the element's own box, so it does not paint over the content around it. */
+::view-transition-group(.slide-right),
+::view-transition-group(.slide-left) {
+	overflow: clip;
+}
+
 ::view-transition-new(.slide-right) {
 	animation: slide-in-from-right var(--horizontal-transition-duration) ease-in-out both;
 }

package/ui/transition/HorizontalTransition.md

@@ -7,6 +7,17 @@ A direction-aware `<Transition>` preset that slides its children horizontally
 - Slides right by default and when the type is `"forward"`; slides left when the type is `"back"`.
 - Set the direction with `setTransitionType("forward" | "back")` inside a `startTransition()` callback before navigating — see `<Transition>`.
 - Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`).
+- The old and new content slide a full width apart, so they sit edge to edge and never overlap.
+- The slide is clipped to the element's own box (`overflow: clip` on the group), so it does not paint over the content around it.
+- During the slide, the snapshots paint above fixed elements such as a bottom bar. To keep a fixed element on top, give it its own `view-transition-name` and put the slide groups below it:
+
+  ```css
+  ::view-transition-group(.slide-right),
+  ::view-transition-group(.slide-left) {
+    z-index: -1;
+  }
+  ```
+
 - Under `prefers-reduced-motion: reduce` the slide distance is forced to `0`, so the transition degrades to an opacity-only crossfade with no positional movement (large viewport-level slides are exactly what the preference exists to suppress).
 
 ## Usage
@@ -33,7 +44,7 @@ function navigate(direction: "forward" | "back", url: string) {
 
 | Variable | Styles | Default |
 |---|---|---|
-| `--horizontal-transition-size` | Slide distance for the enter/leave keyframes | `25vw` |
+| `--horizontal-transition-size` | Slide distance for the enter/leave keyframes. A percentage is of the element's own width. | `100%` |
 | `--horizontal-transition-duration` | Duration of the slide keyframes | `var(--duration-normal)` |
 
 **Global tokens it reads** — `--duration-normal`.

package/ui/transition/VerticalTransition.css

@@ -1,6 +1,11 @@
-@layer base {
+@import url("../style/layers.css");
+@import url("../style/Duration.module.css");
+
+/* Global CSS, not a CSS module — see `Transition.css` for why. */
+@layer defaults {
 	:root {
-		--vertical-transition-size: 25vh;
+		/* A percentage is of the snapshot's own size, so the old and new content sit edge to edge and never overlap. */
+		--vertical-transition-size: 100%;
 		--vertical-transition-duration: var(--duration-normal);
 	}
 }
@@ -53,6 +58,12 @@
 	}
 }
 
+/* Clip the slide to the element's own box, so it does not paint over the content around it. */
+::view-transition-group(.slide-up),
+::view-transition-group(.slide-down) {
+	overflow: clip;
+}
+
 ::view-transition-new(.slide-up) {
 	animation: slide-in-from-bottom var(--vertical-transition-duration) ease-in-out both;
 }

package/ui/transition/VerticalTransition.md

@@ -7,6 +7,17 @@ A direction-aware `<Transition>` preset that slides its children vertically —
 - Slides down by default and when the type is `"forward"`; slides up when the type is `"back"`.
 - Set the direction with `setTransitionType("forward" | "back")` inside a `startTransition()` callback before navigating — see `<Transition>`.
 - Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`).
+- The old and new content slide a full height apart, so they sit edge to edge and never overlap.
+- The slide is clipped to the element's own box (`overflow: clip` on the group), so it does not paint over the content around it.
+- During the slide, the snapshots paint above fixed elements such as a bottom bar. To keep a fixed element on top, give it its own `view-transition-name` and put the slide groups below it:
+
+  ```css
+  ::view-transition-group(.slide-up),
+  ::view-transition-group(.slide-down) {
+    z-index: -1;
+  }
+  ```
+
 - Under `prefers-reduced-motion: reduce` the slide distance is forced to `0`, so the transition degrades to an opacity-only crossfade with no positional movement (large viewport-level slides are exactly what the preference exists to suppress).
 
 ## Usage
@@ -23,7 +34,7 @@ import { VerticalTransition } from "shelving/ui";
 
 | Variable | Styles | Default |
 |---|---|---|
-| `--vertical-transition-size` | Slide distance for the enter/leave keyframes | `25vh` |
+| `--vertical-transition-size` | Slide distance for the enter/leave keyframes. A percentage is of the element's own height. | `100%` |
 | `--vertical-transition-duration` | Duration of the slide keyframes | `var(--duration-normal)` |
 
 **Global tokens it reads** — `--duration-normal`.

package/util/format.d.ts

@@ -89,6 +89,7 @@ export interface UnitFormatOptions extends FormatOptions, Omit<Intl.NumberFormat
  * - Unfortunately the list of supported units changes in different browsers.
  * - Ideally we want to format units using the built-in formatting so things like translation and internationalisation are covered.
  * - But we want provide fallback formatting for unsupported units, and do something _good enough_ job in most cases.
+ * - Compound units like `kilometer-per-hour` use the built-in formatting when both parts are supported.
  *
  * @param num Quantity to format.
  * @param unit Unit reference to format the quantity as, e.g. `"minute"` or `"product"`.
@@ -97,6 +98,20 @@ export interface UnitFormatOptions extends FormatOptions, Omit<Intl.NumberFormat
  * @see https://shelving.cc/util/format/formatUnit
  */
 export declare function formatUnit(num: number, unit: string, options?: UnitFormatOptions): string;
+/**
+ * Format the short name of a unit on its own, e.g. `"km"` or `"min"`, with no number.
+ *
+ * - Uses the `Intl.NumberFormat` short name when the browser supports the unit, so the name is translated (e.g. `"Std."` for `hour` in German).
+ * - Falls back to `options.abbr`, then to the unit reference itself, when the browser does not support the unit.
+ * - Gives the name for an amount of one, so some units in some locales differ from their plural form (e.g. `"day"` not `"days"`).
+ *
+ * @param unit Unit reference, e.g. `"minute"` or `"product"`.
+ * @returns The short name of the unit, e.g. `"min"`.
+ * @example formatUnitAbbr("kilometer") // "km"
+ * @example formatUnitAbbr("dog", { abbr: "🐶" }) // "🐶"
+ * @see https://shelving.cc/util/format/formatUnitAbbr
+ */
+export declare function formatUnitAbbr(unit: string, options?: UnitFormatOptions): string;
 /**
  * Options we use for currency formatting.
  *

package/util/format.js

@@ -45,6 +45,7 @@ export function formatRange(from, to, options) {
  * - Unfortunately the list of supported units changes in different browsers.
  * - Ideally we want to format units using the built-in formatting so things like translation and internationalisation are covered.
  * - But we want provide fallback formatting for unsupported units, and do something _good enough_ job in most cases.
+ * - Compound units like `kilometer-per-hour` use the built-in formatting when both parts are supported.
  *
  * @param num Quantity to format.
  * @param unit Unit reference to format the quantity as, e.g. `"minute"` or `"product"`.
@@ -54,7 +55,7 @@ export function formatRange(from, to, options) {
  */
 export function formatUnit(num, unit, options) {
     // Check if the unit is supported by the browser.
-    if (Intl.supportedValuesOf("unit").includes(unit))
+    if (_isIntlUnit(unit))
         return Intl.NumberFormat(options?.locale, { ...options, style: "unit", unit }).format(num);
     // Otherwise, use the default number format.
     const str = Intl.NumberFormat(options?.locale, { ...options, style: "decimal" }).format(num);
@@ -63,6 +64,43 @@ export function formatUnit(num, unit, options) {
         return `${str} ${str === "1" ? one : many}`;
     return `${str}${unitDisplay === "narrow" ? "" : " "}${abbr}`; // "short" is the default.
 }
+/**
+ * Format the short name of a unit on its own, e.g. `"km"` or `"min"`, with no number.
+ *
+ * - Uses the `Intl.NumberFormat` short name when the browser supports the unit, so the name is translated (e.g. `"Std."` for `hour` in German).
+ * - Falls back to `options.abbr`, then to the unit reference itself, when the browser does not support the unit.
+ * - Gives the name for an amount of one, so some units in some locales differ from their plural form (e.g. `"day"` not `"days"`).
+ *
+ * @param unit Unit reference, e.g. `"minute"` or `"product"`.
+ * @returns The short name of the unit, e.g. `"min"`.
+ * @example formatUnitAbbr("kilometer") // "km"
+ * @example formatUnitAbbr("dog", { abbr: "🐶" }) // "🐶"
+ * @see https://shelving.cc/util/format/formatUnitAbbr
+ */
+export function formatUnitAbbr(unit, options) {
+    if (_isIntlUnit(unit)) {
+        const parts = Intl.NumberFormat(options?.locale, { style: "unit", unit, unitDisplay: "short" }).formatToParts(1);
+        const abbr = parts
+            .filter(p => p.type === "unit")
+            .map(p => p.value)
+            .join("");
+        if (abbr)
+            return abbr;
+    }
+    return options?.abbr ?? unit;
+}
+/** Units that `Intl.NumberFormat` supports in this environment (created on first use). */
+let _INTL_UNITS;
+/**
+ * Is a unit supported by `Intl.NumberFormat` in this environment?
+ * - Compound units like `kilometer-per-hour` are supported when both parts are supported.
+ * - Returns `false` where `Intl.supportedValuesOf()` does not exist.
+ */
+function _isIntlUnit(unit) {
+    _INTL_UNITS ??= new Set(typeof Intl.supportedValuesOf === "function" ? Intl.supportedValuesOf("unit") : []);
+    const parts = unit.split("-per-");
+    return parts.length <= 2 && parts.every(part => _INTL_UNITS?.has(part));
+}
 /**
  * Format a currency amount (based on the user's browser language settings).
  *

package/util/units.d.ts

@@ -1,4 +1,4 @@
-import { type UnitFormatOptions } from "./format.js";
+import { type FormatOptions, type UnitFormatOptions } from "./format.js";
 import { ImmutableMap, type MapKey } from "./map.js";
 import type { ImmutableObject } from "./object.js";
 /** Conversion from one unit to another (either an amount to multiple by, or a function to convert). */
@@ -80,6 +80,17 @@ export declare class Unit<K extends string> {
      * @see https://shelving.cc/util/units/Unit/format
      */
     format(amount: number, options?: UnitFormatOptions): string;
+    /**
+     * Format the short name of this unit on its own, e.g. `km` or `min`, with no number.
+     * - Uses `Intl.NumberFormat` if this is a supported unit, so the name is translated.
+     * - Falls back to this unit's `abbr` option, then to its key.
+     *
+     * @param options Formatting options, e.g. `locale`.
+     * @returns The short name of this unit.
+     * @example LENGTH_UNITS.require("kilometer").formatAbbr() // "km"
+     * @see https://shelving.cc/util/units/Unit/formatAbbr
+     */
+    formatAbbr(options?: FormatOptions): string;
 }
 /**
  * Represent a list of related units of measure (e.g. all length units).
@@ -153,7 +164,7 @@ export type AngleUnitKey = MapKey<typeof ANGLE_UNITS>;
 export declare const MASS_UNITS: UnitList<"gram" | "kilogram" | "milligram" | "ounce" | "pound" | "stone">;
 export type MassUnitKey = MapKey<typeof MASS_UNITS>;
 /** Length units. */
-export declare const LENGTH_UNITS: UnitList<"centimeter" | "foot" | "furlong" | "inch" | "kilometer" | "meter" | "mile" | "millimeter" | "yard">;
+export declare const LENGTH_UNITS: UnitList<"centimeter" | "foot" | "inch" | "kilometer" | "meter" | "mile" | "millimeter" | "yard">;
 export type LengthUnitKey = MapKey<typeof LENGTH_UNITS>;
 /** Speed units. */
 export declare const SPEED_UNITS: UnitList<"kilometer-per-hour" | "meter-per-second" | "mile-per-hour">;
@@ -162,7 +173,7 @@ export type SpeedUnitKey = MapKey<typeof SPEED_UNITS>;
 export declare const AREA_UNITS: UnitList<"acre" | "hectare" | "square-centimeter" | "square-foot" | "square-inch" | "square-kilometer" | "square-meter" | "square-millimeter" | "square-yard">;
 export type AreaUnitKey = MapKey<typeof AREA_UNITS>;
 /** Volume units. */
-export declare const VOLUME_UNITS: UnitList<"cubic-centimeter" | "cubic-foot" | "cubic-inch" | "cubic-meter" | "cubic-yard" | "imperial-fluid-ounce" | "imperial-gallon" | "imperial-pint" | "imperial-quart" | "liter" | "milliliter" | "us-fluid-ounce" | "us-gallon" | "us-pint" | "us-quart">;
+export declare const VOLUME_UNITS: UnitList<"cubic-centimeter" | "cubic-foot" | "cubic-inch" | "cubic-meter" | "cubic-yard" | "imperial-fluid-ounce" | "imperial-gallon" | "imperial-pint" | "imperial-quart" | "liter" | "milliliter" | "us-cup" | "us-fluid-ounce" | "us-gallon" | "us-pint" | "us-quart">;
 export type VolumeUnitKey = MapKey<typeof VOLUME_UNITS>;
 /** Temperature units. */
 export declare const TEMPERATURE_UNITS: UnitList<"celsius" | "fahrenheit" | "kelvin">;

package/util/units.js

@@ -1,7 +1,7 @@
 import { RequiredError } from "../error/RequiredError.js";
 import { ValueError } from "../error/ValueError.js";
 import { HOUR, MILLION, NNBSP } from "./constants.js";
-import { formatUnit } from "./format.js";
+import { formatUnit, formatUnitAbbr } from "./format.js";
 import { ImmutableMap } from "./map.js";
 import { getProps } from "./object.js";
 /** Convert an amount using a `Conversion. */
@@ -113,6 +113,19 @@ export class Unit {
     format(amount, options) {
         return formatUnit(amount, this.key, { ...this.options, ...options });
     }
+    /**
+     * Format the short name of this unit on its own, e.g. `km` or `min`, with no number.
+     * - Uses `Intl.NumberFormat` if this is a supported unit, so the name is translated.
+     * - Falls back to this unit's `abbr` option, then to its key.
+     *
+     * @param options Formatting options, e.g. `locale`.
+     * @returns The short name of this unit.
+     * @example LENGTH_UNITS.require("kilometer").formatAbbr() // "km"
+     * @see https://shelving.cc/util/units/Unit/formatAbbr
+     */
+    formatAbbr(options) {
+        return formatUnitAbbr(this.key, { ...this.options, ...options });
+    }
 }
 /**
  * Represent a list of related units of measure (e.g. all length units).
@@ -176,7 +189,6 @@ const IN_PER_MI = 63360;
 const FT_PER_YD = 3;
 const FT_PER_MI = 5280;
 const YD_PER_MI = 1760;
-const YD_PER_FUR = 220;
 const MM_PER_CM = 10;
 const MM_PER_M = 1000;
 const MM_PER_KM = MILLION;
@@ -244,7 +256,6 @@ export const LENGTH_UNITS = new UnitList({
     inch: { abbr: "in", many: "inches", to: { millimeter: MM_PER_IN } },
     foot: { abbr: "ft", many: "feet", to: { millimeter: IN_PER_FT * MM_PER_IN, inch: IN_PER_FT } },
     yard: { abbr: "yd", to: { millimeter: IN_PER_YD * MM_PER_IN, inch: IN_PER_YD, foot: FT_PER_YD } },
-    furlong: { abbr: "fur", to: { millimeter: IN_PER_YD * MM_PER_IN * YD_PER_FUR, foot: YD_PER_FUR * FT_PER_YD, yard: YD_PER_FUR } },
     mile: { abbr: "mi", to: { millimeter: MM_PER_MI, yard: YD_PER_MI, foot: FT_PER_MI, inch: IN_PER_MI } },
 });
 /** Speed units. */
@@ -252,7 +263,7 @@ export const SPEED_UNITS = new UnitList({
     // Metric.
     "meter-per-second": { abbr: "m/s", one: "meter per second", many: "meters per second", to: { "kilometer-per-hour": 3.6 } },
     "kilometer-per-hour": {
-        abbr: "kph",
+        abbr: "km/h",
         one: "kilometer per hour",
         many: "kilometers per hour",
         to: { "meter-per-second": MM_PER_KM / HOUR },
@@ -293,28 +304,43 @@ export const VOLUME_UNITS = new UnitList({
     "cubic-meter": { abbr: "m³", to: { milliliter: MILLION } },
     // US.
     "us-fluid-ounce": {
-        abbr: `fl${NNBSP}oz`,
+        abbr: `US${NNBSP}fl${NNBSP}oz`,
         one: "US fluid ounce",
         many: "US fluid ounces",
         to: { milliliter: (US_IN3_PER_GAL * ML_PER_IN3) / 128 },
     },
-    "us-pint": { abbr: "pt", one: "US pint", to: { milliliter: (US_IN3_PER_GAL * ML_PER_IN3) / 8, "us-fluid-ounce": 16 } },
+    "us-cup": { abbr: `US${NNBSP}cup`, one: "US cup", to: { milliliter: (US_IN3_PER_GAL * ML_PER_IN3) / 16, "us-fluid-ounce": 8 } },
+    "us-pint": {
+        abbr: `US${NNBSP}pt`,
+        one: "US pint",
+        to: { milliliter: (US_IN3_PER_GAL * ML_PER_IN3) / 8, "us-cup": 2, "us-fluid-ounce": 16 },
+    },
     "us-quart": {
-        abbr: "qt",
+        abbr: `US${NNBSP}qt`,
         one: "US quart",
-        to: { milliliter: (US_IN3_PER_GAL * ML_PER_IN3) / 4, "us-pint": 2, "us-fluid-ounce": 32 },
+        to: { milliliter: (US_IN3_PER_GAL * ML_PER_IN3) / 4, "us-pint": 2, "us-cup": 4, "us-fluid-ounce": 32 },
     },
     "us-gallon": {
-        abbr: "gal",
+        abbr: `US${NNBSP}gal`,
         one: "US gallon",
-        to: { milliliter: US_IN3_PER_GAL * ML_PER_IN3, "us-quart": 4, "us-pint": 8, "us-fluid-ounce": 128 },
+        to: { milliliter: US_IN3_PER_GAL * ML_PER_IN3, "us-quart": 4, "us-pint": 8, "us-cup": 16, "us-fluid-ounce": 128 },
     },
     // Imperial.
-    "imperial-fluid-ounce": { abbr: `fl${NNBSP}oz`, to: { milliliter: IMP_ML_PER_GAL / 160 } },
-    "imperial-pint": { abbr: "pt", to: { milliliter: IMP_ML_PER_GAL / 8, "imperial-fluid-ounce": 20 } },
-    "imperial-quart": { abbr: "qt", to: { milliliter: IMP_ML_PER_GAL / 4, "imperial-pint": 2, "imperial-fluid-ounce": 40 } },
+    "imperial-fluid-ounce": {
+        abbr: `fl${NNBSP}oz${NNBSP}Imp.`,
+        one: "imperial fluid ounce",
+        many: "imperial fluid ounces",
+        to: { milliliter: IMP_ML_PER_GAL / 160 },
+    },
+    "imperial-pint": { abbr: `pt${NNBSP}Imp.`, one: "imperial pint", to: { milliliter: IMP_ML_PER_GAL / 8, "imperial-fluid-ounce": 20 } },
+    "imperial-quart": {
+        abbr: `qt${NNBSP}Imp.`,
+        one: "imperial quart",
+        to: { milliliter: IMP_ML_PER_GAL / 4, "imperial-pint": 2, "imperial-fluid-ounce": 40 },
+    },
     "imperial-gallon": {
-        abbr: "gal",
+        abbr: `gal${NNBSP}Imp.`,
+        one: "imperial gallon",
         to: { milliliter: IMP_ML_PER_GAL, "imperial-quart": 4, "imperial-pint": 8, "imperial-fluid-ounce": 160 },
     },
     "cubic-inch": { abbr: "in³", many: "cubic inches", to: { milliliter: ML_PER_IN3 } },