@stridge/noctis 1.0.0-beta.0

package/dist/components/preview-card/preview-card.d.ts

@@ -0,0 +1,182 @@
+import { preview_card_d_exports } from "../../primitives/preview-card.js";
+import { descriptionProps, mediaProps, metaProps, popupProps, titleProps, triggerProps } from "./preview-card.props.js";
+import { ComponentPropsWithoutRef, ReactElement } from "react";
+
+//#region src/components/preview-card/preview-card.d.ts
+/**
+ * Owns the open state and shares it with the trigger and popup. Wraps Base UI's PreviewCard, which
+ * opens on hover-intent (a delay before opening, a grace period before closing) and on keyboard focus
+ * of the trigger, and dismisses on `Escape` / outside interaction.
+ */
+declare function PreviewCardRoot(props: PreviewCard.Root.Props): ReactElement;
+/**
+ * The link that opens the preview card — renders an `<a>` and styles itself: an accent link that
+ * underlines on hover/focus, shows a focus-visible ring, and keeps a persistent underline while its
+ * card is open (no hand-authored classes needed). Opens on hover after `delay` ms (default 500, with a
+ * `closeDelay` grace period on leave, default 200) and **instantly** on keyboard focus. Compose your
+ * own anchor through `render` (e.g. a Next.js `Link`); the trigger stays inline so it sits naturally
+ * inside running text. It does not open on touch — tapping follows the link, so the link must convey
+ * the destination.
+ */
+declare function PreviewCardTrigger({
+  className,
+  delay,
+  closeDelay,
+  ...props
+}: PreviewCard.Trigger.Props): ReactElement;
+/**
+ * The floating preview surface — portaled, elevated, flush, rounded, and animated — holding the
+ * preview content. Opens above or below the trigger (whichever fits), aligned to its center, and caps
+ * between a min and max width. Renders through `<Surface elevation="menu">` so it re-derives the
+ * anchored-overlay scope it shares with the menu and popover. It caps at the collision-aware
+ * `--available-height` and scrolls its inner `viewport` past that — the same flush, rounded, elevated
+ * chassis as the popover. Pass any preview markup as children — a `Media`/`Title`/`Description`/`Meta`
+ * stack, or your own. When several triggers share one card (give each a `payload` and read it from
+ * `Root`'s render-function child), the popup swaps to the active trigger's content.
+ */
+declare function PreviewCardPopup({
+  side,
+  align,
+  sideOffset,
+  alignOffset,
+  collisionPadding,
+  anchor,
+  className,
+  style,
+  children,
+  ...props
+}: PreviewCard.Popup.Props): ReactElement;
+/**
+ * A media frame for the top of a card — reserves a fixed aspect ratio up front (so the card doesn't
+ * reflow when a thumbnail loads), clips its overflow, and rounds its corners a step tighter than the
+ * popup. Drop an `<img>` (which covers the frame) or a skeleton inside.
+ */
+declare function PreviewCardMedia({
+  className,
+  ...props
+}: PreviewCard.Media.Props): ReactElement;
+/** The card's heading — lifts to the foreground role at medium weight on a tight leading. Renders a `<div>`. */
+declare function PreviewCardTitle({
+  className,
+  ...props
+}: PreviewCard.Title.Props): ReactElement;
+/** Supporting copy under the title — inherits the popup's secondary body tone. Renders a `<p>`. */
+declare function PreviewCardDescription({
+  className,
+  ...props
+}: PreviewCard.Description.Props): ReactElement;
+/** A subtle flex row for stats or label/value pairs at the foot of a card. Renders a `<div>`. */
+declare function PreviewCardMeta({
+  className,
+  ...props
+}: PreviewCard.Meta.Props): ReactElement;
+/**
+ * A hover/focus link-preview card: a `Trigger` link opens a floating, elevated `Popup` after a short
+ * intent delay (and on keyboard focus), showing a richer preview of what the link points to. Built on
+ * Base UI's PreviewCard for the hover-intent timing, focus management, and `Escape`/outside-click
+ * dismissal.
+ *
+ * Compose from parts: `PreviewCard.Root` owns the open state, `PreviewCard.Trigger` is the inline link
+ * that opens it (and styles itself), and `PreviewCard.Popup` holds the preview content. Lay that
+ * content out with the thin rich-content slots — `PreviewCard.Media` (a thumbnail/OG image frame),
+ * `PreviewCard.Title`, `PreviewCard.Description`, and `PreviewCard.Meta` (a stats row). Noctis previews
+ * are flush against their anchor — there is no arrow/caret part (Base UI offers one; this system
+ * doesn't use it) — and the popup is never modal: the page stays interactive beneath it.
+ *
+ * Styling is precompiled in `preview-card.css`, keyed off each part's prefixed `data-slot`. Each part
+ * also carries the D12 `props()` escape hatch via `Object.assign` (e.g. `PreviewCard.Popup.props()`),
+ * returning a spreadable `{ "data-slot": "noctis-preview-card-<part>" }` bag for a foreign element a
+ * `<PreviewCard.*>` can't wrap.
+ *
+ * The runtime compound is a plain object (kept tree-shakeable); per-part prop and state types are
+ * exposed through the matching `PreviewCard` namespace — e.g. `PreviewCard.Popup.Props`.
+ */
+declare const PreviewCard: {
+  Root: typeof PreviewCardRoot;
+  Trigger: typeof PreviewCardTrigger & {
+    props: typeof triggerProps;
+  };
+  Popup: typeof PreviewCardPopup & {
+    props: typeof popupProps;
+  };
+  Media: typeof PreviewCardMedia & {
+    props: typeof mediaProps;
+  };
+  Title: typeof PreviewCardTitle & {
+    props: typeof titleProps;
+  };
+  Description: typeof PreviewCardDescription & {
+    props: typeof descriptionProps;
+  };
+  Meta: typeof PreviewCardMeta & {
+    props: typeof metaProps;
+  };
+};
+/**
+ * Per-part prop and state types, mirroring Base UI's `Component.Part.Props` convention. Types-only —
+ * it emits no runtime code and merges with the `PreviewCard` object above, so `PreviewCard.Popup` is
+ * the component value while `PreviewCard.Popup.Props` is its prop type.
+ */
+declare namespace PreviewCard {
+  namespace Root {
+    type Props = preview_card_d_exports.PreviewCard.Root.Props;
+    type State = preview_card_d_exports.PreviewCard.Root.State;
+  }
+  namespace Trigger {
+    type Props = preview_card_d_exports.PreviewCard.Trigger.Props;
+    type State = preview_card_d_exports.PreviewCard.Trigger.State;
+  }
+  namespace Popup {
+    type Props = preview_card_d_exports.PreviewCard.Popup.Props & {
+      /**
+       * Which side of the anchor to open on. Defaults to Base UI's collision-aware placement
+       * (`bottom`, flipping to `top` when there's no room below).
+       */
+      side?: preview_card_d_exports.PreviewCard.Positioner.Props["side"];
+      /**
+       * Alignment along that side.
+       * @default "center"
+       */
+      align?: preview_card_d_exports.PreviewCard.Positioner.Props["align"];
+      /**
+       * Gap from the anchor, in px. Kept tight so the flush card reads as tied to its anchor and
+       * the hover grace area stays small.
+       * @default 4
+       */
+      sideOffset?: number;
+      /**
+       * Shift along the alignment axis, in px.
+       */
+      alignOffset?: number;
+      /**
+       * Minimum space kept from the viewport edge when avoiding collisions, in px.
+       * @default 8
+       */
+      collisionPadding?: preview_card_d_exports.PreviewCard.Positioner.Props["collisionPadding"];
+      /**
+       * The element to anchor and position against. Defaults to the `PreviewCard.Trigger`; pass an
+       * element, a ref, or a `() => Element | null` getter to anchor a triggerless, fully
+       * controlled card to an arbitrary element (e.g. a canvas node tracked on hover).
+       */
+      anchor?: preview_card_d_exports.PreviewCard.Positioner.Props["anchor"];
+    };
+  }
+  namespace Media {
+    /** Props for {@link PreviewCard.Media} — a `<div>` aspect-ratio frame. */
+    type Props = ComponentPropsWithoutRef<"div">;
+  }
+  namespace Title {
+    /** Props for {@link PreviewCard.Title} — a `<div>` heading. */
+    type Props = ComponentPropsWithoutRef<"div">;
+  }
+  namespace Description {
+    /** Props for {@link PreviewCard.Description} — a `<p>` of supporting copy. */
+    type Props = ComponentPropsWithoutRef<"p">;
+  }
+  namespace Meta {
+    /** Props for {@link PreviewCard.Meta} — a `<div>` stats row. */
+    type Props = ComponentPropsWithoutRef<"div">;
+  }
+}
+//#endregion
+export { PreviewCard };

package/dist/components/preview-card/preview-card.js

@@ -0,0 +1,146 @@
+"use client";
+import { Surface } from "../surface/surface.js";
+import { preview_card_exports } from "../../primitives/preview-card.js";
+import { PREVIEW_CARD_SLOTS } from "./preview-card.slots.js";
+import { descriptionProps, mediaProps, metaProps, popupProps, titleProps, triggerProps } from "./preview-card.props.js";
+import clsx$1 from "clsx";
+import { jsx } from "react/jsx-runtime";
+//#region src/components/preview-card/preview-card.tsx
+/** Noctis's snappier hover-intent defaults — a touch quicker than Base UI's 600/300. */
+const DEFAULT_DELAY = 500;
+const DEFAULT_CLOSE_DELAY = 200;
+/**
+* Owns the open state and shares it with the trigger and popup. Wraps Base UI's PreviewCard, which
+* opens on hover-intent (a delay before opening, a grace period before closing) and on keyboard focus
+* of the trigger, and dismisses on `Escape` / outside interaction.
+*/
+function PreviewCardRoot(props) {
+	return /* @__PURE__ */ jsx(preview_card_exports.PreviewCard.Root, { ...props });
+}
+/**
+* The link that opens the preview card — renders an `<a>` and styles itself: an accent link that
+* underlines on hover/focus, shows a focus-visible ring, and keeps a persistent underline while its
+* card is open (no hand-authored classes needed). Opens on hover after `delay` ms (default 500, with a
+* `closeDelay` grace period on leave, default 200) and **instantly** on keyboard focus. Compose your
+* own anchor through `render` (e.g. a Next.js `Link`); the trigger stays inline so it sits naturally
+* inside running text. It does not open on touch — tapping follows the link, so the link must convey
+* the destination.
+*/
+function PreviewCardTrigger({ className, delay = DEFAULT_DELAY, closeDelay = DEFAULT_CLOSE_DELAY, ...props }) {
+	return /* @__PURE__ */ jsx(preview_card_exports.PreviewCard.Trigger, {
+		"data-slot": PREVIEW_CARD_SLOTS.trigger,
+		delay,
+		closeDelay,
+		className: clsx$1(className),
+		...props
+	});
+}
+/**
+* The floating preview surface — portaled, elevated, flush, rounded, and animated — holding the
+* preview content. Opens above or below the trigger (whichever fits), aligned to its center, and caps
+* between a min and max width. Renders through `<Surface elevation="menu">` so it re-derives the
+* anchored-overlay scope it shares with the menu and popover. It caps at the collision-aware
+* `--available-height` and scrolls its inner `viewport` past that — the same flush, rounded, elevated
+* chassis as the popover. Pass any preview markup as children — a `Media`/`Title`/`Description`/`Meta`
+* stack, or your own. When several triggers share one card (give each a `payload` and read it from
+* `Root`'s render-function child), the popup swaps to the active trigger's content.
+*/
+function PreviewCardPopup({ side, align = "center", sideOffset = 4, alignOffset, collisionPadding = 8, anchor, className, style, children, ...props }) {
+	return /* @__PURE__ */ jsx(preview_card_exports.PreviewCard.Portal, { children: /* @__PURE__ */ jsx(preview_card_exports.PreviewCard.Positioner, {
+		anchor,
+		side,
+		align,
+		sideOffset,
+		alignOffset,
+		collisionPadding,
+		"data-slot": PREVIEW_CARD_SLOTS.positioner,
+		children: /* @__PURE__ */ jsx(preview_card_exports.PreviewCard.Popup, {
+			"data-slot": PREVIEW_CARD_SLOTS.popup,
+			render: /* @__PURE__ */ jsx(Surface, {
+				elevation: "menu",
+				bordered: true,
+				shadow: "popover"
+			}),
+			style: {
+				transformOrigin: "var(--transform-origin)",
+				maxHeight: "var(--available-height)",
+				...style
+			},
+			className: clsx$1(className),
+			...props,
+			children: /* @__PURE__ */ jsx("div", {
+				"data-slot": PREVIEW_CARD_SLOTS.viewport,
+				"data-custom-scrollbar": true,
+				children
+			})
+		})
+	}) });
+}
+/**
+* A media frame for the top of a card — reserves a fixed aspect ratio up front (so the card doesn't
+* reflow when a thumbnail loads), clips its overflow, and rounds its corners a step tighter than the
+* popup. Drop an `<img>` (which covers the frame) or a skeleton inside.
+*/
+function PreviewCardMedia({ className, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		"data-slot": PREVIEW_CARD_SLOTS.media,
+		className: clsx$1(className),
+		...props
+	});
+}
+/** The card's heading — lifts to the foreground role at medium weight on a tight leading. Renders a `<div>`. */
+function PreviewCardTitle({ className, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		"data-slot": PREVIEW_CARD_SLOTS.title,
+		className: clsx$1(className),
+		...props
+	});
+}
+/** Supporting copy under the title — inherits the popup's secondary body tone. Renders a `<p>`. */
+function PreviewCardDescription({ className, ...props }) {
+	return /* @__PURE__ */ jsx("p", {
+		"data-slot": PREVIEW_CARD_SLOTS.description,
+		className: clsx$1(className),
+		...props
+	});
+}
+/** A subtle flex row for stats or label/value pairs at the foot of a card. Renders a `<div>`. */
+function PreviewCardMeta({ className, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		"data-slot": PREVIEW_CARD_SLOTS.meta,
+		className: clsx$1(className),
+		...props
+	});
+}
+/**
+* A hover/focus link-preview card: a `Trigger` link opens a floating, elevated `Popup` after a short
+* intent delay (and on keyboard focus), showing a richer preview of what the link points to. Built on
+* Base UI's PreviewCard for the hover-intent timing, focus management, and `Escape`/outside-click
+* dismissal.
+*
+* Compose from parts: `PreviewCard.Root` owns the open state, `PreviewCard.Trigger` is the inline link
+* that opens it (and styles itself), and `PreviewCard.Popup` holds the preview content. Lay that
+* content out with the thin rich-content slots — `PreviewCard.Media` (a thumbnail/OG image frame),
+* `PreviewCard.Title`, `PreviewCard.Description`, and `PreviewCard.Meta` (a stats row). Noctis previews
+* are flush against their anchor — there is no arrow/caret part (Base UI offers one; this system
+* doesn't use it) — and the popup is never modal: the page stays interactive beneath it.
+*
+* Styling is precompiled in `preview-card.css`, keyed off each part's prefixed `data-slot`. Each part
+* also carries the D12 `props()` escape hatch via `Object.assign` (e.g. `PreviewCard.Popup.props()`),
+* returning a spreadable `{ "data-slot": "noctis-preview-card-<part>" }` bag for a foreign element a
+* `<PreviewCard.*>` can't wrap.
+*
+* The runtime compound is a plain object (kept tree-shakeable); per-part prop and state types are
+* exposed through the matching `PreviewCard` namespace — e.g. `PreviewCard.Popup.Props`.
+*/
+const PreviewCard = {
+	Root: PreviewCardRoot,
+	Trigger: Object.assign(PreviewCardTrigger, { props: triggerProps }),
+	Popup: Object.assign(PreviewCardPopup, { props: popupProps }),
+	Media: Object.assign(PreviewCardMedia, { props: mediaProps }),
+	Title: Object.assign(PreviewCardTitle, { props: titleProps }),
+	Description: Object.assign(PreviewCardDescription, { props: descriptionProps }),
+	Meta: Object.assign(PreviewCardMeta, { props: metaProps })
+};
+//#endregion
+export { PreviewCard };

package/dist/components/preview-card/preview-card.props.d.ts

@@ -0,0 +1,37 @@
+//#region src/components/preview-card/preview-card.props.d.ts
+/** A spreadable data-attribute prop bag — the shape every `PreviewCard.*.props()` returns. */
+type PreviewCardPartProps = {
+  /** The slot value the matching `preview-card.css` rules anchor on. */"data-slot": string; /** Forwarded verbatim — styling is attribute-driven, so this is an optional consumer passthrough. */
+  className?: string;
+};
+/** Common shape: every part's `.props()` accepts an optional `className` passthrough. */
+interface PreviewCardPropsArgs {
+  /** Forwarded verbatim onto the returned prop bag. */
+  className?: string;
+}
+/** Trigger prop bag: just the slot anchor. */
+declare function triggerProps({
+  className
+}?: PreviewCardPropsArgs): PreviewCardPartProps;
+/** Popup prop bag: just the slot anchor (the base surface paint is owned by the composed Surface). */
+declare function popupProps({
+  className
+}?: PreviewCardPropsArgs): PreviewCardPartProps;
+/** Media prop bag: just the slot anchor (the aspect-ratio frame; an `<img>` covers it). */
+declare function mediaProps({
+  className
+}?: PreviewCardPropsArgs): PreviewCardPartProps;
+/** Title prop bag: just the slot anchor (lifts to the foreground role at medium weight). */
+declare function titleProps({
+  className
+}?: PreviewCardPropsArgs): PreviewCardPartProps;
+/** Description prop bag: just the slot anchor (inherits the popup's secondary body tone). */
+declare function descriptionProps({
+  className
+}?: PreviewCardPropsArgs): PreviewCardPartProps;
+/** Meta prop bag: just the slot anchor (a subtle flex row for stats / label-value pairs). */
+declare function metaProps({
+  className
+}?: PreviewCardPropsArgs): PreviewCardPartProps;
+//#endregion
+export { descriptionProps, mediaProps, metaProps, popupProps, titleProps, triggerProps };

package/dist/components/preview-card/preview-card.props.js

@@ -0,0 +1,48 @@
+import { PREVIEW_CARD_SLOTS } from "./preview-card.slots.js";
+//#region src/components/preview-card/preview-card.props.ts
+/**
+* The D12 unified variant contract for PreviewCard — a per-part set of `props(...)` builders that each
+* return a **spreadable props object** of the form `{ "data-slot": "noctis-preview-card-<part>" }`,
+* derived from the part's inputs.
+*
+* Under the single-`data-slot` anchor model the `data-slot` is the only styling hook needed —
+* `preview-card.css` keys every rule off it — so spreading a part's `props()` onto a *foreign*
+* element styles it as that part:
+*
+*     <a {...PreviewCard.Trigger.props()}>@noctis</a>
+*     // → <a data-slot="noctis-preview-card-trigger">
+*
+* The escape hatch carries no className (styling is attribute-driven); an optional `className`
+* passthrough is accepted and forwarded verbatim. The same mapping is emitted as data from the token
+* graph (`generated/declarations.json`) so non-React / agent consumers can hand-write the markup.
+*/
+const withClassName = (bag, className) => className === void 0 ? bag : {
+	...bag,
+	className
+};
+/** Trigger prop bag: just the slot anchor. */
+function triggerProps({ className } = {}) {
+	return withClassName({ "data-slot": PREVIEW_CARD_SLOTS.trigger }, className);
+}
+/** Popup prop bag: just the slot anchor (the base surface paint is owned by the composed Surface). */
+function popupProps({ className } = {}) {
+	return withClassName({ "data-slot": PREVIEW_CARD_SLOTS.popup }, className);
+}
+/** Media prop bag: just the slot anchor (the aspect-ratio frame; an `<img>` covers it). */
+function mediaProps({ className } = {}) {
+	return withClassName({ "data-slot": PREVIEW_CARD_SLOTS.media }, className);
+}
+/** Title prop bag: just the slot anchor (lifts to the foreground role at medium weight). */
+function titleProps({ className } = {}) {
+	return withClassName({ "data-slot": PREVIEW_CARD_SLOTS.title }, className);
+}
+/** Description prop bag: just the slot anchor (inherits the popup's secondary body tone). */
+function descriptionProps({ className } = {}) {
+	return withClassName({ "data-slot": PREVIEW_CARD_SLOTS.description }, className);
+}
+/** Meta prop bag: just the slot anchor (a subtle flex row for stats / label-value pairs). */
+function metaProps({ className } = {}) {
+	return withClassName({ "data-slot": PREVIEW_CARD_SLOTS.meta }, className);
+}
+//#endregion
+export { descriptionProps, mediaProps, metaProps, popupProps, titleProps, triggerProps };

package/dist/components/preview-card/preview-card.slots.d.ts

@@ -0,0 +1,22 @@
+//#region src/components/preview-card/preview-card.slots.d.ts
+/**
+ * The `data-*` hooks `PreviewCard` stamps on its parts, for host-side styling and tests. The slot
+ * value marks each rendered element; the state attributes are emitted by Base UI's PreviewCard —
+ * pair a slot with a state to target, say, the popup only while it transitions in.
+ */
+declare enum PreviewCardDataAttributes {
+  /** The trigger element (and every rendered part). */
+  trigger = "data-slot",
+  /** Present on the trigger while its preview card is open. */
+  popupOpen = "data-popup-open",
+  /** The side of the anchor the popup actually rendered on (`bottom`, `top`, …). */
+  side = "data-side",
+  /** Present on the popup for the first frame after mount — the transition's start state. */
+  startingStyle = "data-starting-style",
+  /** Present on the popup while it transitions out before unmounting. */
+  endingStyle = "data-ending-style",
+  /** Present on the popup when the change should not animate (focus open, dismissal). */
+  instant = "data-instant"
+}
+//#endregion
+export { PreviewCardDataAttributes };

package/dist/components/preview-card/preview-card.slots.js

@@ -0,0 +1,39 @@
+//#region src/components/preview-card/preview-card.slots.ts
+/**
+* The slot vocabulary every `PreviewCard` part stamps as its `data-slot`. The authored source the
+* orchestration file reads from, prefixed `noctis-{component}-{part}` (the precompiled
+* `preview-card.css` keys every rule off these anchors); SLOTS.md still generates from the
+* token-graph declaration.
+*/
+const PREVIEW_CARD_SLOTS = {
+	trigger: "noctis-preview-card-trigger",
+	positioner: "noctis-preview-card-positioner",
+	popup: "noctis-preview-card-popup",
+	viewport: "noctis-preview-card-viewport",
+	media: "noctis-preview-card-media",
+	title: "noctis-preview-card-title",
+	description: "noctis-preview-card-description",
+	meta: "noctis-preview-card-meta"
+};
+/**
+* The `data-*` hooks `PreviewCard` stamps on its parts, for host-side styling and tests. The slot
+* value marks each rendered element; the state attributes are emitted by Base UI's PreviewCard —
+* pair a slot with a state to target, say, the popup only while it transitions in.
+*/
+let PreviewCardDataAttributes = /* @__PURE__ */ function(PreviewCardDataAttributes) {
+	/** The trigger element (and every rendered part). */
+	PreviewCardDataAttributes["trigger"] = "data-slot";
+	/** Present on the trigger while its preview card is open. */
+	PreviewCardDataAttributes["popupOpen"] = "data-popup-open";
+	/** The side of the anchor the popup actually rendered on (`bottom`, `top`, …). */
+	PreviewCardDataAttributes["side"] = "data-side";
+	/** Present on the popup for the first frame after mount — the transition's start state. */
+	PreviewCardDataAttributes["startingStyle"] = "data-starting-style";
+	/** Present on the popup while it transitions out before unmounting. */
+	PreviewCardDataAttributes["endingStyle"] = "data-ending-style";
+	/** Present on the popup when the change should not animate (focus open, dismissal). */
+	PreviewCardDataAttributes["instant"] = "data-instant";
+	return PreviewCardDataAttributes;
+}({});
+//#endregion
+export { PREVIEW_CARD_SLOTS, PreviewCardDataAttributes };

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

@@ -0,0 +1,3 @@
+import { ProgressSize } from "./progress.context.js";
+import { Progress } from "./progress.js";
+import { ProgressDataAttributes } from "./progress.slots.js";

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

@@ -0,0 +1,9 @@
+//#region src/components/progress/progress.context.d.ts
+/** Status tint of the task outcome — `neutral` by default; the others tint the fill to a status role. */
+type ProgressTone = "neutral" | "success" | "warning" | "danger";
+/** Track thickness — `sm` (thin) or `md` (default). */
+type ProgressSize = "sm" | "md";
+/** Caption placement — `top` (header row above the track) or `side` (inline beside it). */
+type ProgressLabels = "top" | "side";
+//#endregion
+export { ProgressLabels, ProgressSize, ProgressTone };

package/dist/components/progress/progress.context.js

@@ -0,0 +1,13 @@
+"use client";
+import { createContext, use } from "react";
+//#region src/components/progress/progress.context.ts
+const ProgressContext = createContext(null);
+const ProgressProvider = ProgressContext.Provider;
+/** Read the bar context, throwing a named error when a part renders outside `Progress.Root`. */
+function useProgressContext(part) {
+	const context = use(ProgressContext);
+	if (context === null) throw new Error(`Progress.${part} must be rendered inside <Progress.Root>.`);
+	return context;
+}
+//#endregion
+export { ProgressProvider, useProgressContext };

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

@@ -0,0 +1,139 @@
+import { Progress as Progress$1 } from "../../primitives/progress/progress.js";
+import { ProgressLabels, ProgressSize, ProgressTone } from "./progress.context.js";
+import { ProgressIndicatorPropsArgs, ProgressPartProps, ProgressRootPropsArgs, indicatorProps, labelProps, rootProps, trackProps, valueProps } from "./progress.props.js";
+import { ReactElement, ReactNode } from "react";
+
+//#region src/components/progress/progress.d.ts
+/**
+ * Owns the value and shares the resolved `tone`/`size`/`labels` with its parts. Determinate when `value`
+ * is a number (`0`–`max`, `max` defaulting to `100`); indeterminate when `value` is `null`. Pass `tone`
+ * to tint the fill to a task outcome — `danger` for a failed upload, `warning` for at-risk, `success`
+ * for done; `neutral` (the default) keeps the active accent. The noctis primitive injects the active
+ * locale so the formatted value reads in the reader's language.
+ */
+declare function ProgressRoot({
+  tone,
+  size,
+  labels,
+  thickness,
+  className,
+  style,
+  children,
+  ...props
+}: Progress.Root.Props): ReactElement;
+/** The recessed rail the indicator fills. Holds a single `Progress.Indicator`. */
+declare function ProgressTrack({
+  className,
+  ...props
+}: Progress.Track.Props): ReactElement;
+/** The accent fill. Base UI sizes its inline width to the value; an empty value sweeps it indeterminately. */
+declare function ProgressIndicator({
+  className,
+  ...props
+}: Progress.Indicator.Props): ReactElement;
+/** The progress bar's accessible label. Place it in a header row beside `Progress.Value`. */
+declare function ProgressLabel({
+  className,
+  ...props
+}: Progress.Label.Props): ReactElement;
+/** The formatted completion text, localized via the injected locale. Pass a child function to format it. */
+declare function ProgressValue({
+  className,
+  ...props
+}: Progress.Value.Props): ReactElement;
+/**
+ * A progress bar for a task's completion: an accent fill over a recessed track, in two thicknesses. It is
+ * determinate when given a `value` (`0`–`max`) and indeterminate when `value` is `null`, in which case a
+ * sliver sweeps the track. Built on Base UI's Progress, so the root carries the correct `progressbar`
+ * role and ARIA value semantics, the value formats for the reader's locale, and the indeterminate sweep
+ * respects `prefers-reduced-motion`.
+ *
+ * Compose from parts: `Progress.Root` owns the value and the shared `tone`/`size`/`labels`,
+ * `Progress.Track` holds one `Progress.Indicator`, and an optional `Progress.Label` + `Progress.Value`
+ * caption the bar — the root lays them out above (`labels="top"`) or beside (`labels="side"`) the track.
+ *
+ * The runtime compound is a plain object (kept tree-shakeable); per-part prop and state types are exposed
+ * through the matching `Progress` namespace — e.g. `Progress.Value.Props`.
+ */
+declare const Progress: {
+  /** Owns the value and the shared tone/size/labels. `Progress.Root.props({ tone, size, labels })` → its spreadable prop bag. */Root: typeof ProgressRoot & {
+    props: typeof rootProps;
+  }; /** The recessed rail. `Progress.Track.props()` → its spreadable prop bag. */
+  Track: typeof ProgressTrack & {
+    props: typeof trackProps;
+  }; /** The accent fill. `Progress.Indicator.props({ indeterminate })` → its spreadable prop bag for a foreign element. */
+  Indicator: typeof ProgressIndicator & {
+    props: typeof indicatorProps;
+  }; /** The accessible label. `Progress.Label.props()` → its spreadable prop bag. */
+  Label: typeof ProgressLabel & {
+    props: typeof labelProps;
+  }; /** The formatted value text. `Progress.Value.props()` → its spreadable prop bag. */
+  Value: typeof ProgressValue & {
+    props: typeof valueProps;
+  };
+};
+/**
+ * Per-part prop and state types, mirroring Base UI's `Component.Part.Props` convention. Types-only — it
+ * emits no runtime code and merges with the `Progress` object above, so `Progress.Value` is the component
+ * value while `Progress.Value.Props` is its prop type.
+ */
+declare namespace Progress {
+  /** Status tint of the task outcome — `neutral`, `success`, `warning`, or `danger`. */
+  type Tone = ProgressTone;
+  /** Track thickness — `sm` or `md`. */
+  type Size = ProgressSize;
+  /** Caption placement — `top` or `side`. */
+  type Labels = ProgressLabels;
+  /** The spreadable data-attribute prop bag every `Progress.*.props()` returns (D12). */
+  type PartProps = ProgressPartProps;
+  namespace Root {
+    type Props = Omit<Progress$1.Root.Props, "className" | "children"> & {
+      /**
+       * Status tint of the task outcome — `danger` for failed, `warning` for at-risk, `success`
+       * for done. `neutral` keeps the active accent fill.
+       * @default "neutral"
+       */
+      tone?: ProgressTone;
+      /**
+       * Track thickness preset.
+       * @default "md"
+       */
+      size?: ProgressSize;
+      /**
+       * Caption placement — a header row above the track (`top`) or inline beside it (`side`).
+       * @default "top"
+       */
+      labels?: ProgressLabels;
+      /**
+       * An explicit track thickness, overriding the `size` preset. A number is treated as `px`; a
+       * string is any CSS length. Writes the public track block-size override var.
+       */
+      thickness?: number | string; /** `Progress.Track` and an optional `Progress.Label` + `Progress.Value`. */
+      children?: ReactNode; /** Classes merged onto the root. */
+      className?: string;
+    };
+    type State = Progress$1.Root.State;
+    /** Argument to the `Progress.Root.props(...)` escape-hatch helper. */
+    type PropsArgs = ProgressRootPropsArgs;
+  }
+  namespace Track {
+    type Props = Progress$1.Track.Props;
+    type State = Progress$1.Track.State;
+  }
+  namespace Indicator {
+    type Props = Progress$1.Indicator.Props;
+    type State = Progress$1.Indicator.State;
+    /** Argument to the `Progress.Indicator.props(...)` escape-hatch helper. */
+    type PropsArgs = ProgressIndicatorPropsArgs;
+  }
+  namespace Label {
+    type Props = Progress$1.Label.Props;
+    type State = Progress$1.Label.State;
+  }
+  namespace Value {
+    type Props = Progress$1.Value.Props;
+    type State = Progress$1.Value.State;
+  }
+}
+//#endregion
+export { Progress };