@nanisoft/prism-ui 0.10.2 → 0.15.0

package/dist/components/ui/price.d.ts

@@ -0,0 +1,144 @@
+import type { ComponentProps, ReactNode } from 'react';
+/**
+ * The props the Price accepts.
+ *
+ * The first half is a union rather than a set of optional props, and it is a
+ * union for the reason `HeroAction` is one: a caller who supplies `format` has
+ * said the platform is not formatting this price, and with `currency` merely
+ * optional the type system cannot see that `locale`, `currency` and
+ * `maximumFractionDigits` are all dead on that arm. Only a union lets the
+ * exception be seen. A caller whose currency has no `Intl` data, or whose price
+ * is really a range or a phrase, passes `format` and is not also made to invent a
+ * currency code for a formatter that will never read it.
+ *
+ * The second half is the presentation, and it is shared by both arms because a
+ * formatter changes what the words are and not how they are set.
+ */
+export type PriceProps = Omit<ComponentProps<'div'>, 'children'> & ({
+    /**
+     * The amount, in the currency's own minor units. Omit it and the Price
+     * renders nothing at all; see the JSDoc on the Component.
+     */
+    amount?: number;
+    /**
+     * The ISO 4217 code of the currency, such as `USD`, `EUR` or `JPY`.
+     *
+     * Required on this arm because it is the one prop that says what the
+     * number means, and a currency code is a machine value a platform
+     * recognises rather than a sentence anyone has to translate.
+     */
+    currency: string;
+    /**
+     * The locale the platform formats for. Omit it for the runtime's own
+     * default, which is the right answer on a server and the wrong one on a
+     * page that serves several languages, so a multilingual consumer should
+     * pass it.
+     */
+    locale?: Intl.LocalesArgument;
+    /**
+     * How many fraction digits the amount is shown with.
+     *
+     * Omit it and the currency's own rule applies, which is two for a
+     * dollar and zero for a yen. That default is the reason this prop exists
+     * at all: a price the consumer has decided has no meaningful cents gets
+     * `0` here rather than a trailing `.00` on every line of a table.
+     */
+    maximumFractionDigits?: number;
+    /** Replace the platform's formatter entirely. On this arm it is not passed. */
+    format?: never;
+} | {
+    /** The amount, in whatever unit `format` reads. */
+    amount?: number;
+    /**
+     * The words for an amount, replacing `Intl` completely.
+     *
+     * The escape hatch, and the reason it replaces rather than adjusts: a
+     * currency with no data in the runtime's tables, an amount that is a
+     * range or a phrase, a price in a unit no `style` names, and a consumer
+     * whose accounting renders in a currency and reads in another. All four
+     * are one function away.
+     */
+    format: (amount: number) => string;
+    locale?: never;
+    currency?: never;
+    maximumFractionDigits?: never;
+}) & {
+    /**
+     * The amount this one replaced, shown struck through beside it.
+     *
+     * A number in the same unit as `amount`, and formatted by whatever formats
+     * `amount`, so the two are never rendered by two different rules.
+     */
+    compareAt?: number;
+    /**
+     * What the amount is per, set after the amount it belongs to.
+     *
+     * The caller's words and the caller's punctuation, because "per month" and
+     * "/mo" and "a month" are three products' decisions. A Price that shipped
+     * one of them would be shipping a pricing model.
+     */
+    period?: ReactNode;
+    /**
+     * The type-scale step the amount is set at. @defaultValue 'lg'
+     *
+     * Four steps and no arbitrary value, so a price is always at a size the type
+     * scale authored. The default is `lg` because a price is usually the largest
+     * thing in a narrow component and the surrounding layout decides the rest;
+     * `xl` is a step up for a price that is the page's subject, and the step
+     * above that is out of reach on purpose, because a price set larger than the
+     * title beside it stops reading as a price and starts reading as a headline.
+     */
+    size?: 'sm' | 'md' | 'lg' | 'xl';
+};
+/**
+ * A monetary amount with its currency, and optionally what it replaced.
+ *
+ * **The formatter is `Intl`, and the argument is that Prism is not entitled to
+ * a currency.** A library that hardcoded a dollar sign and two decimal places
+ * makes two claims about every consumer that installs it: that the consumer's
+ * market is the one that writes dollars, and that the consumer's prices have two
+ * decimal places of meaning. The first is wrong in most of the world and the
+ * second is wrong for a unit price, a seat, a token and a whole number of
+ * licences. `Intl` is the platform's own answer to both questions, it is already
+ * localised, and it is already in every runtime a browser has, so a Price that
+ * wrote its own would be a second formatter in every consumer's bundle. The cost
+ * is worth naming: `Intl` is a constructor rather than a template, so a server
+ * Component constructs one per request rather than one at build, and a page that
+ * prints a thousand prices constructs a thousand formatters. A consumer whose
+ * prices are on a hot path caches the formatter itself, which is a better place
+ * for that knowledge than a design system.
+ *
+ * **The comparison is a strikethrough, and the rejected alternative is a
+ * Badge.** A strikethrough is the convention, so a reader who has seen a
+ * comparison price in a shop, a search result and a receipt recognises it
+ * without being taught. A Badge would put a filled surface and a colour on a
+ * claim about a price, and the claim is the consumer's: whether the amount it
+ * replaced was ever charged is a fact about the consumer's billing, not a state
+ * this Component can colour. A comparison struck through in the muted foreground
+ * is subordinate in three ways at once, by the line through it, by the step down
+ * from the amount, and by the ink, and it is the amount that is read.
+ *
+ * **No amount renders nothing, and that is the honest answer rather than a
+ * zero.** A Price with no `amount` is a price a product has not computed yet: a
+ * first load, a currency that has not been resolved, a plan whose region has no
+ * price. An empty fragment says "there is no price here", which is true. A dash,
+ * a question mark or a zero says "the price is zero", which is a claim about a
+ * consumer's revenue that this Component has no standing to make and a reader
+ * has no way to disprove. This is the same decision `FactList` makes for an empty
+ * list, and the reason it is worth copying rather than inventing: a Component
+ * that renders a placeholder where it has no data is a Component that has chosen
+ * a sentence, and a design system's job is not to choose one on a consumer's
+ * behalf. The cost is a layout that closes up and reopens as the amount arrives,
+ * which is the same cost every empty state in this system carries.
+ *
+ * **The period belongs to the amount, so it sits with the amount and before the
+ * comparison.** A comparison rendered between them would read as another
+ * per-period figure, and a struck-through price per month next to a monthly
+ * price is a comparison nobody intended.
+ *
+ * It is a server Component: no hook, no state, and the formatting is arithmetic
+ * over props that happens to go through the platform.
+ */
+declare function Price({ className, amount, format, locale, currency, maximumFractionDigits, compareAt, period, size, ...props }: PriceProps): import("react").JSX.Element | null;
+export { Price };
+//# sourceMappingURL=price.d.ts.map

package/dist/components/ui/price.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"price.d.ts","sourceRoot":"","sources":["../../../src/components/ui/price.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AA2CtD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,GAC9D,CACI;IACE;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;OAMG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,IAAI,CAAC,eAAe,CAAA;IAC7B;;;;;;;OAOG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,+EAA+E;IAC/E,MAAM,CAAC,EAAE,KAAK,CAAA;CACf,GACD;IACE,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;;;OAQG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAA;IAClC,MAAM,CAAC,EAAE,KAAK,CAAA;IACd,QAAQ,CAAC,EAAE,KAAK,CAAA;IAChB,qBAAqB,CAAC,EAAE,KAAK,CAAA;CAC9B,CACJ,GAAG;IACF;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;CACjC,CAAA;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,iBAAS,KAAK,CAAC,EACb,SAAS,EACT,MAAM,EACN,MAAM,EACN,MAAM,EACN,QAAQ,EACR,qBAAqB,EACrB,SAAS,EACT,MAAM,EACN,IAAW,EACX,GAAG,KAAK,EACT,EAAE,UAAU,sCAoDZ;AAED,OAAO,EAAE,KAAK,EAAE,CAAA"}

package/dist/components/ui/price.js

@@ -0,0 +1,107 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from '../../lib/utils.js';
+/*
+ * **This is filed under Data display and not Typography, and the reason is that a
+ * price is a figure rather than a piece of running text.** It was authored under
+ * Typography, and the site build refused the tree, which is the disagreement
+ * `DESIGN.md` says the Category folder is supposed to catch: a Component filed
+ * under a folder that is not its Category still publishes its route and still
+ * leaves the sidebar, so the taxonomy catches it rather than a reader finding an
+ * item filed in the wrong place. `Typography` in this package is the family that
+ * styles running text: `Prose`, `Mark`, `Kbd` and the type scale itself. A price
+ * is a number with a currency, a period and a comparison, which is the same shape
+ * as `Metric` and belongs beside it. The two are the pair a reader meets in one
+ * place on a pricing page, and a design system that filed them in different
+ * categories would be telling a reader they are different kinds of thing.
+ */
+/** The authored type-scale steps a Price amount is set at, and nothing else. */
+const AMOUNT_SIZE = {
+    sm: 'text-sm',
+    md: 'text-base',
+    lg: 'text-lg',
+    xl: 'text-xl',
+};
+/**
+ * The step the period and the comparison are set at: one below the amount.
+ *
+ * The comparison has to be subordinate in three ways at once, and the size is one
+ * of them. A fixed `text-sm` would leave the amount and its comparison the same
+ * size at `size="sm"`, so the map steps down rather than pinning, and a
+ * comparison that is the same size as the price beside it stops reading as a
+ * comparison.
+ */
+const SECONDARY_SIZE = {
+    sm: 'text-xs',
+    md: 'text-sm',
+    lg: 'text-sm',
+    xl: 'text-lg',
+};
+/**
+ * A monetary amount with its currency, and optionally what it replaced.
+ *
+ * **The formatter is `Intl`, and the argument is that Prism is not entitled to
+ * a currency.** A library that hardcoded a dollar sign and two decimal places
+ * makes two claims about every consumer that installs it: that the consumer's
+ * market is the one that writes dollars, and that the consumer's prices have two
+ * decimal places of meaning. The first is wrong in most of the world and the
+ * second is wrong for a unit price, a seat, a token and a whole number of
+ * licences. `Intl` is the platform's own answer to both questions, it is already
+ * localised, and it is already in every runtime a browser has, so a Price that
+ * wrote its own would be a second formatter in every consumer's bundle. The cost
+ * is worth naming: `Intl` is a constructor rather than a template, so a server
+ * Component constructs one per request rather than one at build, and a page that
+ * prints a thousand prices constructs a thousand formatters. A consumer whose
+ * prices are on a hot path caches the formatter itself, which is a better place
+ * for that knowledge than a design system.
+ *
+ * **The comparison is a strikethrough, and the rejected alternative is a
+ * Badge.** A strikethrough is the convention, so a reader who has seen a
+ * comparison price in a shop, a search result and a receipt recognises it
+ * without being taught. A Badge would put a filled surface and a colour on a
+ * claim about a price, and the claim is the consumer's: whether the amount it
+ * replaced was ever charged is a fact about the consumer's billing, not a state
+ * this Component can colour. A comparison struck through in the muted foreground
+ * is subordinate in three ways at once, by the line through it, by the step down
+ * from the amount, and by the ink, and it is the amount that is read.
+ *
+ * **No amount renders nothing, and that is the honest answer rather than a
+ * zero.** A Price with no `amount` is a price a product has not computed yet: a
+ * first load, a currency that has not been resolved, a plan whose region has no
+ * price. An empty fragment says "there is no price here", which is true. A dash,
+ * a question mark or a zero says "the price is zero", which is a claim about a
+ * consumer's revenue that this Component has no standing to make and a reader
+ * has no way to disprove. This is the same decision `FactList` makes for an empty
+ * list, and the reason it is worth copying rather than inventing: a Component
+ * that renders a placeholder where it has no data is a Component that has chosen
+ * a sentence, and a design system's job is not to choose one on a consumer's
+ * behalf. The cost is a layout that closes up and reopens as the amount arrives,
+ * which is the same cost every empty state in this system carries.
+ *
+ * **The period belongs to the amount, so it sits with the amount and before the
+ * comparison.** A comparison rendered between them would read as another
+ * per-period figure, and a struck-through price per month next to a monthly
+ * price is a comparison nobody intended.
+ *
+ * It is a server Component: no hook, no state, and the formatting is arithmetic
+ * over props that happens to go through the platform.
+ */
+function Price({ className, amount, format, locale, currency, maximumFractionDigits, compareAt, period, size = 'lg', ...props }) {
+    // No amount is no price, and an empty fragment is the whole answer. See the
+    // JSDoc above for why this is not a placeholder.
+    if (amount === undefined)
+        return null;
+    // Built only on the arm that has no formatter of its own, which is the arm
+    // whose union member required a currency, so the platform never sees
+    // `style: 'currency'` without one.
+    const read = format ??
+        ((value) => new Intl.NumberFormat(locale, {
+            style: 'currency',
+            currency,
+            // Undefined rather than omitted, which the platform reads as "the
+            // currency's own rule", so a price with no `maximumFractionDigits` prop
+            // gets a yen's zero and a dollar's two without this Component choosing.
+            maximumFractionDigits,
+        }).format(value));
+    return (_jsxs("div", { "data-slot": "price", className: cn('flex flex-wrap items-baseline gap-x-2', className), ...props, children: [_jsx("span", { "data-slot": "price-amount", className: cn('font-semibold tracking-tight tabular-nums', AMOUNT_SIZE[size]), children: read(amount) }), period === undefined ? null : (_jsx("span", { "data-slot": "price-period", className: cn('text-muted-foreground', SECONDARY_SIZE[size]), children: period })), compareAt === undefined ? null : (_jsx("s", { "data-slot": "price-compare", className: cn('text-muted-foreground tabular-nums', SECONDARY_SIZE[size]), children: read(compareAt) }))] }));
+}
+export { Price };

package/dist/components/ui/product-mark.d.ts

@@ -1,4 +1,4 @@
-import type { PackId } from '../../theming';
+import type { PackId } from '../../theming/index.js';
 /**
  * The three sizes a product mark is drawn at: the mark's diameter and the name
  * beside it, taken together so the two parts of the mark stay in proportion.

package/dist/components/ui/product-mark.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/utils.js';
 /**
  * The full spectrum, as the five series tokens and nothing else.
  *

package/dist/components/ui/product-switcher.d.ts

@@ -1,5 +1,5 @@
 import type { ComponentProps } from 'react';
-import { type ProductMarkProps, type ProductMarkSize } from './product-mark';
+import { type ProductMarkProps, type ProductMarkSize } from './product-mark.js';
 /**
  * One product in the set a switcher moves between.
  *

package/dist/components/ui/product-switcher.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { ProductMark } from './product-mark';
-import { cn } from '../../lib/utils';
+import { ProductMark } from './product-mark.js';
+import { cn } from '../../lib/utils.js';
 /**
  * A switch between the members of a set of products.
  *

package/dist/components/ui/progress.d.ts

@@ -23,6 +23,28 @@ export interface ProgressProps extends ComponentProps<'div'> {
     locale?: Intl.LocalesArgument;
     /** Returns the text alternative announced for a value. */
     getAriaValueText?: (formattedValue: string, value: number | null) => string;
+    /**
+     * The text alternative for the value, already resolved to a string.
+     *
+     * **This exists because `getAriaValueText` cannot cross a server boundary, and
+     * `Progress` is a client Component.** A Block that composes this one and is
+     * itself a server Component has to hand the announced text over as data, and a
+     * function prop from a server Component to a client Component is a build error
+     * in every framework that draws that line, not a warning. The rule is worth
+     * stating once: a callback prop is only expressible when the caller is already
+     * in the client graph, and a published Component that composes another published
+     * Component has to offer the data form for the case where it is not.
+     *
+     * `valueText` wins over `getAriaValueText` when both are passed, because a
+     * string the caller computed is the one they meant; a thrown diagnostic says so
+     * rather than silently preferring either.
+     *
+     * **Pass it only when you have a sentence, because leaving it off is now the
+     * default rather than a way to suppress one.** `ProgressRoot` computes an
+     * `aria-valuetext` of its own, and this Component used to overwrite it with
+     * nothing on every bar. See the note at the call site for the mechanism.
+     */
+    valueText?: string;
 }
 /**
  * A bar that reports how far a task has progressed.
@@ -32,7 +54,39 @@ export interface ProgressProps extends ComponentProps<'div'> {
  * control: the reader watches it, and an interrupting task uses an Alert
  * instead. Pass `value={null}` for a task of unknown length, where the bar is
  * announced as indeterminate.
+ *
+ * **A bar announces a sentence, not only a number, and the sentence is the
+ * default rather than something you have to supply.** `aria-valuenow` is the
+ * position on the scale; `aria-valuetext` is what a reader actually hears for it,
+ * and Base UI computes one for every bar: the value as a percentage of the range
+ * for a determinate task, and `indeterminate progress` for an unknown one. Pass
+ * `valueText` when your task has a better sentence than a percentage, which most
+ * real ones do: "42 of 300 files", "step 3 of 7", "6 minutes remaining". Passing
+ * `getAriaValueText` instead computes one in the browser, and the two are mutually
+ * exclusive because they are two different answers to the same question.
+ *
+ * **The fill is a transform and the transform is the whole of its geometry.**
+ * The indicator is as wide as the track at every value and is scaled along the
+ * reading axis, so advancing a bar is a compositor animation rather than a layout
+ * one. `Progress` is one of the two or three most-composed Components in this
+ * package, which is why this is stated here rather than left as an
+ * implementation detail: an animated `width` makes the browser settle layout on
+ * every frame of every bar on every page that has one, and the cost is paid by the
+ * consumer who composed the most bars rather than by the one who wrote the bar.
+ *
+ * **A consumer who styled the indicator's width has to move with it.** A rule that
+ * sized or constrained `[data-slot="progress-indicator"]` was sizing a box the
+ * component no longer resizes, and the honest replacement is a rule on its
+ * `transform`, on the track's `height`, or on the width of the track itself.
+ *
+ * **The scale runs from the inline start edge in both directions**, and it takes an
+ * `rtl:` variant to say so rather than a logical property, because CSS has no
+ * logical keyword for `transform-origin` and Tailwind 4.3's `origin` utility ships
+ * the nine physical positions and nothing else. `origin-left` is the inline start
+ * under a left-to-right `dir` and `rtl:origin-right` is the inline start under a
+ * right-to-left one, which is the same edge Base UI's own `inset-inline-start: 0`
+ * anchors the fill to, so the bar reads from the same end in either direction.
  */
-declare function Progress({ className, ...props }: ProgressProps): import("react").JSX.Element;
+declare function Progress({ className, valueText, getAriaValueText, value, max, min, ...props }: ProgressProps): import("react").JSX.Element;
 export { Progress };
 //# sourceMappingURL=progress.d.ts.map

package/dist/components/ui/progress.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../../../src/components/ui/progress.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAI3C;;;;;GAKG;AACH,MAAM,WAAW,aAAc,SAAQ,cAAc,CAAC,KAAK,CAAC;IAC1D;;;;;OAKG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,2CAA2C;IAC3C,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,yCAAyC;IACzC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,wEAAwE;IACxE,MAAM,CAAC,EAAE,IAAI,CAAC,mBAAmB,CAAA;IACjC,iDAAiD;IACjD,MAAM,CAAC,EAAE,IAAI,CAAC,eAAe,CAAA;IAC7B,0DAA0D;IAC1D,gBAAgB,CAAC,EAAE,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,MAAM,CAAA;CAC5E;AAED;;;;;;;;GAQG;AACH,iBAAS,QAAQ,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,aAAa,+BAkBvD;AAED,OAAO,EAAE,QAAQ,EAAE,CAAA"}
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../../../src/components/ui/progress.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAI3C;;;;;GAKG;AACH,MAAM,WAAW,aAAc,SAAQ,cAAc,CAAC,KAAK,CAAC;IAC1D;;;;;OAKG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,2CAA2C;IAC3C,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,yCAAyC;IACzC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,wEAAwE;IACxE,MAAM,CAAC,EAAE,IAAI,CAAC,mBAAmB,CAAA;IACjC,iDAAiD;IACjD,MAAM,CAAC,EAAE,IAAI,CAAC,eAAe,CAAA;IAC7B,0DAA0D;IAC1D,gBAAgB,CAAC,EAAE,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,MAAM,CAAA;IAC3E;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AA0CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,iBAAS,QAAQ,CAAC,EAChB,SAAS,EACT,SAAS,EACT,gBAAgB,EAChB,KAAK,EACL,GAAS,EACT,GAAO,EACP,GAAG,KAAK,EACT,EAAE,aAAa,+BAwFf;AAED,OAAO,EAAE,QAAQ,EAAE,CAAA"}

package/dist/components/ui/progress.js

@@ -1,7 +1,47 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Progress as ProgressPrimitive } from '@base-ui/react/progress';
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/utils.js';
+/**
+ * The fraction of the track a value fills, from 0 to 1, or `null` for a task whose
+ * length is unknown.
+ *
+ * **This is Base UI's arithmetic restated, and the restatement is the point.**
+ * `ProgressIndicator` writes `width: <percentage>%` as an inline style and
+ * `ProgressRoot` owns `aria-valuenow`, and both are computed from the same three
+ * numbers this function is handed. A transform needs a unitless factor rather than
+ * a percentage of a box, so the factor has to exist somewhere JavaScript can put
+ * it, and there are exactly two ways to get one: restate the three lines, or parse
+ * the percentage back out of Base UI's own inline style string. The restatement is
+ * the honest one. These are the same three operations in the same order, and a
+ * reader that parses `"68%"` off another package's rendered output is coupled to
+ * the way that package chooses to write it rather than to what it means.
+ *
+ * `progress.test.tsx` holds the two to each other by asserting the transform
+ * against `aria-valuenow` rather than against a second copy of these three lines,
+ * so a change on either side that the other does not follow is a failing test
+ * rather than a bar that draws one number and announces another.
+ */
+function fillOf(value, min, max) {
+    /*
+     * `null` and the two non-finite numbers are the indeterminate condition, and Base
+     * UI reads all three as one, so this returns no transform at all for exactly the
+     * three cases in which it writes no width either. That symmetry is the whole of
+     * the indeterminate case: there is no transform, so there is nothing to animate
+     * and nothing for a reader who cannot see motion to be missing.
+     */
+    if (value === null || !Number.isFinite(value))
+        return null;
+    const percent = (value - min) * 100 / (max - min);
+    /*
+     * `max === min` is a division by zero rather than a task, and the bar on it is a
+     * bar at zero rather than a bar at `NaN`, which is the reading Base UI clamps to.
+     * The infinities a real value on a reversed range produces need no case of their
+     * own: the same two comparisons resolve them to the nearer bound.
+     */
+    const clamped = Number.isNaN(percent) ? 0 : Math.min(100, Math.max(0, percent));
+    return clamped / 100;
+}
 /**
  * A bar that reports how far a task has progressed.
  *
@@ -10,8 +50,76 @@ import { cn } from '../../lib/utils';
  * control: the reader watches it, and an interrupting task uses an Alert
  * instead. Pass `value={null}` for a task of unknown length, where the bar is
  * announced as indeterminate.
+ *
+ * **A bar announces a sentence, not only a number, and the sentence is the
+ * default rather than something you have to supply.** `aria-valuenow` is the
+ * position on the scale; `aria-valuetext` is what a reader actually hears for it,
+ * and Base UI computes one for every bar: the value as a percentage of the range
+ * for a determinate task, and `indeterminate progress` for an unknown one. Pass
+ * `valueText` when your task has a better sentence than a percentage, which most
+ * real ones do: "42 of 300 files", "step 3 of 7", "6 minutes remaining". Passing
+ * `getAriaValueText` instead computes one in the browser, and the two are mutually
+ * exclusive because they are two different answers to the same question.
+ *
+ * **The fill is a transform and the transform is the whole of its geometry.**
+ * The indicator is as wide as the track at every value and is scaled along the
+ * reading axis, so advancing a bar is a compositor animation rather than a layout
+ * one. `Progress` is one of the two or three most-composed Components in this
+ * package, which is why this is stated here rather than left as an
+ * implementation detail: an animated `width` makes the browser settle layout on
+ * every frame of every bar on every page that has one, and the cost is paid by the
+ * consumer who composed the most bars rather than by the one who wrote the bar.
+ *
+ * **A consumer who styled the indicator's width has to move with it.** A rule that
+ * sized or constrained `[data-slot="progress-indicator"]` was sizing a box the
+ * component no longer resizes, and the honest replacement is a rule on its
+ * `transform`, on the track's `height`, or on the width of the track itself.
+ *
+ * **The scale runs from the inline start edge in both directions**, and it takes an
+ * `rtl:` variant to say so rather than a logical property, because CSS has no
+ * logical keyword for `transform-origin` and Tailwind 4.3's `origin` utility ships
+ * the nine physical positions and nothing else. `origin-left` is the inline start
+ * under a left-to-right `dir` and `rtl:origin-right` is the inline start under a
+ * right-to-left one, which is the same edge Base UI's own `inset-inline-start: 0`
+ * anchors the fill to, so the bar reads from the same end in either direction.
  */
-function Progress({ className, ...props }) {
-    return (_jsx(ProgressPrimitive.Root, { "data-slot": "progress", className: cn('flex w-full flex-col gap-2', className), ...props, children: _jsx(ProgressPrimitive.Track, { "data-slot": "progress-track", className: "bg-muted relative h-2 w-full overflow-hidden rounded-full", children: _jsx(ProgressPrimitive.Indicator, { "data-slot": "progress-indicator", className: "bg-primary h-full rounded-full transition-[width] duration-base ease-out" }) }) }));
+function Progress({ className, valueText, getAriaValueText, value, max = 100, min = 0, ...props }) {
+    /*
+     * The guard is here, above the return, and that is the only place it could be.
+     * The conflict is between two of this Component's own props, so it is decided
+     * before any element exists: no prop merge runs, nothing Base UI does can change
+     * the outcome, and the diagnostic names the choice rather than a framework's
+     * preference. `aria-valuetext` reaching the root is a separate question with a
+     * separate answer, and one does not decide the other.
+     */
+    if (valueText !== undefined && getAriaValueText !== undefined) {
+        throw new Error('Progress: a bar was given both valueText and getAriaValueText, so the announced sentence is two ' +
+            "different answers to the same question and the reader gets whichever one the framework happens to " +
+            'prefer. Pass the one you meant.');
+    }
+    const fill = fillOf(value, min, max);
+    /*
+     * `aria-valuetext` is SPREAD onto the root below rather than assigned, and that
+     * is the whole of this Component's part in what a reader hears.
+     *
+     * `ProgressRoot` builds a default for it: the clamped value formatted as a
+     * percentage of the range for a determinate bar, and `indeterminate progress`
+     * for an unknown one. Base UI's prop merge (`mergeProps` into
+     * `mutablyMergeInto`) assigns every key the caller passes, including an explicit
+     * `undefined`, and the root merges its own `defaultProps` FIRST and the caller's
+     * `elementProps` second. So writing `aria-valuetext={undefined}` here did not
+     * leave the default alone, it replaced it with nothing, on every bar in every
+     * consumer: the value was announced through `aria-valuenow` and the formatted
+     * sentence was never in the tree at all. The same overwrite ate
+     * `getAriaValueText`'s return value, so the callback ran and its answer was
+     * discarded, which is also why `format` and `locale` had nothing to shape.
+     *
+     * Passing the key only when `valueText` is defined is what lets the default
+     * survive. `{...props}` lands after both of this Component's own answers, so a
+     * consumer who writes `aria-valuetext` on the Component directly still wins over
+     * the default underneath, which is the precedence the callback and the string
+     * already have between them.
+     */
+    return (_jsx(ProgressPrimitive.Root, { "data-slot": "progress", className: cn('flex w-full flex-col gap-2', className), value: value, min: min, max: max, ...(valueText !== undefined ? { 'aria-valuetext': valueText } : {}), ...(getAriaValueText ? { getAriaValueText } : {}), ...props, children: _jsx(ProgressPrimitive.Track, { "data-slot": "progress-track", className: "bg-muted relative h-2 w-full overflow-hidden rounded-full", children: _jsx(ProgressPrimitive.Indicator, { "data-slot": "progress-indicator", className: "bg-primary origin-left h-full w-full rounded-full transition-transform duration-base ease-out rtl:origin-right", style: fill === null ? undefined : { width: '100%', transform: `scaleX(${fill})` } }) }) }));
 }
 export { Progress };