shelving 1.291.0 → 1.292.0

package/package.json

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

package/ui/dialog/Modal.md

@@ -8,11 +8,11 @@ The panel inside a `<Dialog>`. `<Dialog>` dims the page; `Modal` gives the conte
 - `Modal` sets its text back to `--tint-00`, so it reads on its own `--tint-100` surface.
 - `DialogsStore.show()` wraps its content in a `<Dialog>` only. It does not add a `Modal`, so put the `Modal` in the content yourself.
 - `Modal` only styles the box. Lay out its contents with the usual block components.
-- A centred `Modal` fills the width of its `<Dialog>`, so set `--dialog-width` to change it. `--modal-width` sets the width of a `left` or `right` panel.
+- A centred `Modal` fills the width of its `<Dialog>`, so set `--dialog-width` to change it. `--modal-width` sets the width of a `left` or `right` panel, and the maximum width of a `top` or `bottom` panel.
 - The `padding` variant (for example `padding="large"`) sets the top and bottom padding, and the `indent` variant sets the left and right padding, the same as on `<Panel>`.
 - The `radius` variant sets the corner radius. On a pinned panel, corners that touch a screen edge stay square.
 - It has a `--shadow-normal` drop shadow by default. Set `shadow="none"`, `shadow="small"` or `shadow="large"` to change it, the same as on `<Card>`.
-- Set `top`, `right`, `bottom`, or `left` to pin the panel to that edge of the screen. A top or bottom panel is full width; a left or right panel is full height. Use these for mobile menus, bottom sheets, and side menus.
+- Set `top`, `right`, `bottom`, or `left` to pin the panel to that edge of the screen. A top or bottom panel is full width up to `--modal-width`, and centred on a wider screen. A left or right panel is full height. Use these for mobile menus, bottom sheets, and side menus.
 - A centred panel fades in and out with its `<Dialog>`. A pinned panel slides in from its edge and out to it, in its own view-transition layer. With reduced motion, a pinned panel fades in place.
 
 ## Usage
@@ -96,11 +96,11 @@ A link click inside a `<Dialog>` closes it, so the menu slides out as the page c
 
 ## Styling
 
-`Modal` paints a shadowed surface with no border. Set `--modal-stroke` (for example `var(--stroke-normal)`) to show the themed border, or `--modal-border` to replace it. A pinned panel then keeps only the border on its inner side. On a pinned panel, only the corners that do not touch a screen edge are round. Override these hooks at `:root` (or any ancestor scope) to retheme.
+`Modal` paints a shadowed surface with no border. Set `--modal-stroke` (for example `var(--stroke-normal)`) to show the themed border, or `--modal-border` to replace it. A pinned panel then has no border on the side that touches the screen edge. On a pinned panel, only the corners that do not touch a screen edge are round. Override these hooks at `:root` (or any ancestor scope) to retheme.
 
 | Variable | Styles | Default |
 |---|---|---|
-| `--modal-width` | Width of a `left` or `right` panel (a centred panel takes `--dialog-width`) | `var(--width-narrow)` |
+| `--modal-width` | Width of a `left` or `right` panel, and maximum width of a `top` or `bottom` panel (a centred panel takes `--dialog-width`) | `var(--width-narrow)` |
 | `--modal-stroke` | Border width | `0` (no border) |
 | `--modal-border` | Border shorthand | `var(--modal-stroke)` solid `--tint-80` |
 | `--modal-radius` | Corner radius (the `radius` variant wins over it) | `var(--radius-normal)` (16px) |

package/ui/dialog/Modal.module.css

@@ -37,10 +37,13 @@
 			view-transition-name: match-element;
 		}
 
+		/* Top and bottom panels fill the screen width up to `--modal-width`, and stay centred when the screen is wider. */
 		&.top,
 		&.bottom {
 			inset-inline: 0;
+			margin-inline: auto;
 			width: auto;
+			max-width: var(--modal-width, var(--width-narrow));
 			max-height: var(--modal-max-height, 100%);
 		}
 
@@ -51,18 +54,16 @@
 			width: var(--modal-width, var(--width-narrow));
 		}
 
-		/* If a theme sets `--modal-stroke` or `--modal-border`, keep only the border on the inner side, because the other sides touch the edges of the screen. */
+		/* If a theme sets `--modal-stroke` or `--modal-border`, remove the border on each side that touches the edge of the screen. */
 		&.top {
 			top: 0;
 			border-top: none;
-			border-inline: none;
 			view-transition-class: modal-top;
 		}
 
 		&.bottom {
 			bottom: 0;
 			border-bottom: none;
-			border-inline: none;
 			view-transition-class: modal-bottom;
 		}
 

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 } },