@stridge/noctis 1.0.0-beta.0

package/dist/components/tooltip/tooltip.d.ts

@@ -0,0 +1,170 @@
+import { tooltip_d_exports } from "../../primitives/tooltip.js";
+import { TooltipPartProps, TooltipPopupPropsArgs, arrowProps, popupProps, triggerProps } from "./tooltip.props.js";
+import { ReactElement } from "react";
+
+//#region src/components/tooltip/tooltip.d.ts
+/**
+ * Shares one open/close delay across a group of tooltips, so once any tooltip in the group has
+ * appeared the next opens instantly (within the group `timeout`). Mount it once high in the tree to
+ * tune the hover delay app-wide; individual `Tooltip.Root`s still work without it.
+ */
+declare function TooltipProvider(props: Tooltip.Provider.Props): ReactElement;
+/**
+ * Owns the open state and shares it with the trigger and popup. Wraps Base UI's Tooltip — it opens on
+ * pointer hover (after a delay) and on keyboard focus, and closes on blur, pointer leave, or `Escape`.
+ *
+ * `disableHoverablePopup` flips to `true` for the plain Noctis bubble — it holds nothing reachable, so
+ * the invisible traversal bridge only risks intercepting pointer events over neighbours. Pass
+ * `disableHoverablePopup={false}` if you ever put something selectable in the popup.
+ */
+declare function TooltipRoot({
+  disableHoverablePopup,
+  ...props
+}: Tooltip.Root.Props): ReactElement;
+/**
+ * The element the tooltip is attached to — hovering or focusing it reveals the bubble. Style it
+ * yourself, or compose another control through `render` (e.g.
+ * `<Tooltip.Trigger render={<Button iconOnly aria-label="Help" startIcon={HelpIcon} />} />`).
+ *
+ * The hover `delay` defaults to 300ms — Base UI's 600 reads laggy for a keyboard-first feel; a
+ * `Provider` still makes grouped hovers instant within its `timeout`.
+ */
+declare function TooltipTrigger({
+  delay,
+  ...props
+}: Tooltip.Trigger.Props): ReactElement;
+/**
+ * The floating bubble — portaled and animated — holding the hint text. Opens flush above the trigger
+ * by default, flipping to another side at the viewport edge. Renders as a `<Surface elevation="menu"
+ * bordered shadow="popover">`, so it paints the engine-derived overlay surface (fill, border, shadow)
+ * shared with the menu and popover.
+ */
+declare function TooltipPopup({
+  side,
+  align,
+  sideOffset,
+  alignOffset,
+  collisionPadding,
+  arrowPadding,
+  collisionBoundary,
+  sticky,
+  className,
+  style,
+  children,
+  ...props
+}: Tooltip.Popup.Props): ReactElement;
+/**
+ * An opt-in caret pointing back at the trigger. Compose it inside `Tooltip.Popup`; the flush bubble is
+ * the default, so render this only where a pointer helps (a cursor-tracked or free-floating hint).
+ * Pair it with a larger `sideOffset` (≈8) so the tip meets the trigger. Mirrors automatically by
+ * `data-side`, including the RTL inline sides.
+ */
+declare function TooltipArrow({
+  className,
+  ...props
+}: Tooltip.Arrow.Props): ReactElement;
+/**
+ * A hint bubble that reveals supplementary text on hover and on keyboard focus. Built on Base UI's
+ * Tooltip for the open/close delays, focus and pointer handling, collision-aware positioning, and
+ * `Escape` dismissal — and decoupled from any particular trigger, so it attaches to whatever control
+ * you pass.
+ *
+ * Compose from parts: `Tooltip.Root` owns the open state, `Tooltip.Trigger` is the anchored control,
+ * and `Tooltip.Popup` is the floating bubble. Wrap a region in `Tooltip.Provider` to share one delay
+ * across many tooltips. The bubble paints the engine-derived overlay surface (the menu/popover family)
+ * and is flush against its anchor by default; render `Tooltip.Arrow` inside the popup for an opt-in
+ * caret where a pointer back to the trigger helps.
+ *
+ * Styling is precompiled in `tooltip.css`, keyed off each part's prefixed `data-slot`. Each part also
+ * carries the D12 `props()` escape hatch via `Object.assign` (e.g. `Tooltip.Popup.props({ open })`),
+ * returning a spreadable `{ "data-slot": "noctis-tooltip-<part>", ...dataAttrs }` bag for a foreign
+ * element a `<Tooltip.*>` can't wrap.
+ *
+ * The runtime compound is a plain object (kept tree-shakeable); per-part prop and state types are
+ * exposed through the matching `Tooltip` namespace — e.g. `Tooltip.Popup.Props`.
+ */
+declare const Tooltip: {
+  Provider: typeof TooltipProvider;
+  Root: typeof TooltipRoot;
+  Trigger: typeof TooltipTrigger & {
+    props: typeof triggerProps;
+  };
+  Popup: typeof TooltipPopup & {
+    props: typeof popupProps;
+  };
+  Arrow: typeof TooltipArrow & {
+    props: typeof arrowProps;
+  };
+};
+/**
+ * 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 `Tooltip` object above, so `Tooltip.Popup` is the
+ * component value while `Tooltip.Popup.Props` is its prop type.
+ */
+declare namespace Tooltip {
+  /** The spreadable data-attribute prop bag every `Tooltip.*.props()` returns (D12). */
+  type PartProps = TooltipPartProps;
+  namespace Provider {
+    type Props = tooltip_d_exports.Tooltip.Provider.Props;
+    type State = tooltip_d_exports.Tooltip.Provider.State;
+  }
+  namespace Root {
+    type Props = tooltip_d_exports.Tooltip.Root.Props;
+    type State = tooltip_d_exports.Tooltip.Root.State;
+  }
+  namespace Trigger {
+    type Props = tooltip_d_exports.Tooltip.Trigger.Props;
+    type State = tooltip_d_exports.Tooltip.Trigger.State;
+  }
+  namespace Popup {
+    type Props = tooltip_d_exports.Tooltip.Popup.Props & {
+      /**
+       * Which side of the trigger to open on. May flip to avoid a viewport collision.
+       * @default "top"
+       */
+      side?: tooltip_d_exports.Tooltip.Positioner.Props["side"];
+      /**
+       * Alignment along that side.
+       * @default "center"
+       */
+      align?: tooltip_d_exports.Tooltip.Positioner.Props["align"];
+      /**
+       * Gap from the trigger, in px.
+       * @default 6
+       */
+      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?: tooltip_d_exports.Tooltip.Positioner.Props["collisionPadding"];
+      /**
+       * Minimum space kept between `Tooltip.Arrow` and the popup's corners, in px. Keeps the
+       * caret from sliding off the edge on an aligned tooltip.
+       */
+      arrowPadding?: tooltip_d_exports.Tooltip.Positioner.Props["arrowPadding"];
+      /**
+       * The element collision detection measures against instead of the viewport — pass a
+       * scroll container so the bubble stays within it.
+       */
+      collisionBoundary?: tooltip_d_exports.Tooltip.Positioner.Props["collisionBoundary"];
+      /**
+       * Keeps the bubble anchored as the trigger scrolls out of view rather than detaching.
+       */
+      sticky?: tooltip_d_exports.Tooltip.Positioner.Props["sticky"];
+    };
+    type State = tooltip_d_exports.Tooltip.Popup.State;
+    /** Argument to the `Tooltip.Popup.props(...)` escape-hatch helper. */
+    type PropsArgs = TooltipPopupPropsArgs;
+  }
+  namespace Arrow {
+    type Props = tooltip_d_exports.Tooltip.Arrow.Props;
+    type State = tooltip_d_exports.Tooltip.Arrow.State;
+  }
+}
+//#endregion
+export { Tooltip };

package/dist/components/tooltip/tooltip.js

@@ -0,0 +1,143 @@
+"use client";
+import { Surface } from "../surface/surface.js";
+import { tooltip_exports } from "../../primitives/tooltip.js";
+import { TOOLTIP_SLOTS } from "./tooltip.slots.js";
+import { arrowProps, popupProps, triggerProps } from "./tooltip.props.js";
+import clsx$1 from "clsx";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/components/tooltip/tooltip.tsx
+/**
+* Shares one open/close delay across a group of tooltips, so once any tooltip in the group has
+* appeared the next opens instantly (within the group `timeout`). Mount it once high in the tree to
+* tune the hover delay app-wide; individual `Tooltip.Root`s still work without it.
+*/
+function TooltipProvider(props) {
+	return /* @__PURE__ */ jsx(tooltip_exports.Tooltip.Provider, { ...props });
+}
+/**
+* Owns the open state and shares it with the trigger and popup. Wraps Base UI's Tooltip — it opens on
+* pointer hover (after a delay) and on keyboard focus, and closes on blur, pointer leave, or `Escape`.
+*
+* `disableHoverablePopup` flips to `true` for the plain Noctis bubble — it holds nothing reachable, so
+* the invisible traversal bridge only risks intercepting pointer events over neighbours. Pass
+* `disableHoverablePopup={false}` if you ever put something selectable in the popup.
+*/
+function TooltipRoot({ disableHoverablePopup = true, ...props }) {
+	return /* @__PURE__ */ jsx(tooltip_exports.Tooltip.Root, {
+		disableHoverablePopup,
+		...props
+	});
+}
+/**
+* The element the tooltip is attached to — hovering or focusing it reveals the bubble. Style it
+* yourself, or compose another control through `render` (e.g.
+* `<Tooltip.Trigger render={<Button iconOnly aria-label="Help" startIcon={HelpIcon} />} />`).
+*
+* The hover `delay` defaults to 300ms — Base UI's 600 reads laggy for a keyboard-first feel; a
+* `Provider` still makes grouped hovers instant within its `timeout`.
+*/
+function TooltipTrigger({ delay = 300, ...props }) {
+	return /* @__PURE__ */ jsx(tooltip_exports.Tooltip.Trigger, {
+		"data-slot": TOOLTIP_SLOTS.trigger,
+		delay,
+		...props
+	});
+}
+/**
+* The floating bubble — portaled and animated — holding the hint text. Opens flush above the trigger
+* by default, flipping to another side at the viewport edge. Renders as a `<Surface elevation="menu"
+* bordered shadow="popover">`, so it paints the engine-derived overlay surface (fill, border, shadow)
+* shared with the menu and popover.
+*/
+function TooltipPopup({ side = "top", align = "center", sideOffset = 6, alignOffset, collisionPadding = 8, arrowPadding, collisionBoundary, sticky, className, style, children, ...props }) {
+	return /* @__PURE__ */ jsx(tooltip_exports.Tooltip.Portal, { children: /* @__PURE__ */ jsx(tooltip_exports.Tooltip.Positioner, {
+		side,
+		align,
+		sideOffset,
+		alignOffset,
+		collisionPadding,
+		arrowPadding,
+		collisionBoundary,
+		sticky,
+		"data-slot": TOOLTIP_SLOTS.positioner,
+		children: /* @__PURE__ */ jsx(tooltip_exports.Tooltip.Popup, {
+			"data-slot": TOOLTIP_SLOTS.popup,
+			render: /* @__PURE__ */ jsx(Surface, {
+				elevation: "menu",
+				bordered: true,
+				shadow: "popover"
+			}),
+			style: {
+				transformOrigin: "var(--transform-origin)",
+				...style
+			},
+			className: clsx$1(className),
+			...props,
+			children
+		})
+	}) });
+}
+/**
+* The sharp caret SVG the arrow renders. Drawn tip-up at a fixed 20×10 geometry; `tooltip.css` rotates
+* the whole arrow per `data-side` and paints the two paths (body in the tooltip hue, edge in the
+* tooltip border role) so the caret seams into the bordered bubble.
+*/
+function ArrowSvg() {
+	return /* @__PURE__ */ jsxs("svg", {
+		width: "20",
+		height: "10",
+		viewBox: "0 0 20 10",
+		fill: "none",
+		"aria-hidden": true,
+		children: [/* @__PURE__ */ jsx("path", {
+			"data-tooltip-arrow": "fill",
+			d: "M9.66437 2.60207L4.80758 6.97318C4.07308 7.63423 3.11989 8 2.13172 8H0V10H20V8H18.5349C17.5468 8 16.5936 7.63423 15.8591 6.97318L11.0023 2.60207C10.622 2.2598 10.0447 2.25979 9.66437 2.60207Z"
+		}), /* @__PURE__ */ jsx("path", {
+			"data-tooltip-arrow": "edge",
+			d: "M8.99542 1.85876C9.75604 1.17425 10.9106 1.17422 11.6713 1.85878L16.5281 6.22989C17.0789 6.72568 17.7938 7.00001 18.5349 7.00001L15.89 7L11.0023 2.60207C10.622 2.2598 10.0447 2.2598 9.66436 2.60207L4.77734 7L2.13171 7.00001C2.87284 7.00001 3.58774 6.72568 4.13861 6.22989L8.99542 1.85876Z"
+		})]
+	});
+}
+/**
+* An opt-in caret pointing back at the trigger. Compose it inside `Tooltip.Popup`; the flush bubble is
+* the default, so render this only where a pointer helps (a cursor-tracked or free-floating hint).
+* Pair it with a larger `sideOffset` (≈8) so the tip meets the trigger. Mirrors automatically by
+* `data-side`, including the RTL inline sides.
+*/
+function TooltipArrow({ className, ...props }) {
+	return /* @__PURE__ */ jsx(tooltip_exports.Tooltip.Arrow, {
+		"data-slot": TOOLTIP_SLOTS.arrow,
+		className: clsx$1(className),
+		...props,
+		children: /* @__PURE__ */ jsx(ArrowSvg, {})
+	});
+}
+/**
+* A hint bubble that reveals supplementary text on hover and on keyboard focus. Built on Base UI's
+* Tooltip for the open/close delays, focus and pointer handling, collision-aware positioning, and
+* `Escape` dismissal — and decoupled from any particular trigger, so it attaches to whatever control
+* you pass.
+*
+* Compose from parts: `Tooltip.Root` owns the open state, `Tooltip.Trigger` is the anchored control,
+* and `Tooltip.Popup` is the floating bubble. Wrap a region in `Tooltip.Provider` to share one delay
+* across many tooltips. The bubble paints the engine-derived overlay surface (the menu/popover family)
+* and is flush against its anchor by default; render `Tooltip.Arrow` inside the popup for an opt-in
+* caret where a pointer back to the trigger helps.
+*
+* Styling is precompiled in `tooltip.css`, keyed off each part's prefixed `data-slot`. Each part also
+* carries the D12 `props()` escape hatch via `Object.assign` (e.g. `Tooltip.Popup.props({ open })`),
+* returning a spreadable `{ "data-slot": "noctis-tooltip-<part>", ...dataAttrs }` bag for a foreign
+* element a `<Tooltip.*>` can't wrap.
+*
+* The runtime compound is a plain object (kept tree-shakeable); per-part prop and state types are
+* exposed through the matching `Tooltip` namespace — e.g. `Tooltip.Popup.Props`.
+*/
+const Tooltip = {
+	Provider: TooltipProvider,
+	Root: TooltipRoot,
+	Trigger: Object.assign(TooltipTrigger, { props: triggerProps }),
+	Popup: Object.assign(TooltipPopup, { props: popupProps }),
+	Arrow: Object.assign(TooltipArrow, { props: arrowProps })
+};
+//#endregion
+export { Tooltip };

package/dist/components/tooltip/tooltip.props.d.ts

@@ -0,0 +1,36 @@
+//#region src/components/tooltip/tooltip.props.d.ts
+/** A spreadable data-attribute prop bag — the shape every `Tooltip.*.props()` returns. */
+type TooltipPartProps = {
+  /** The slot value the matching `tooltip.css` rules anchor on. */"data-slot": string; /** Forwarded verbatim — styling is attribute-driven, so this is an optional consumer passthrough. */
+  className?: string; /** A data-attribute present (empty string) or absent (`undefined`); never `false`. */
+  [attr: `data-${string}`]: string | undefined;
+};
+/** Common shape: every part's `.props()` accepts an optional `className` passthrough. */
+interface BasePropsArgs {
+  /** Forwarded verbatim onto the returned prop bag. */
+  className?: string;
+}
+/** Argument to `Tooltip.Popup.props(...)` — the open state the CSS keys its visibility transition off. */
+interface TooltipPopupPropsArgs extends BasePropsArgs {
+  /** Whether the tooltip is open (drives the visible state via `data-open`). */
+  open?: boolean;
+}
+/** Argument to the trigger's `.props(...)` — no state of its own; just the slot anchor + className. */
+type TooltipTriggerPropsArgs = BasePropsArgs;
+/** Argument to the arrow's `.props(...)` — no computed state; just the slot anchor + className (Base UI stamps `data-side`/`data-align` at runtime). */
+type TooltipArrowPropsArgs = BasePropsArgs;
+/** Trigger prop bag: just the slot anchor. */
+declare function triggerProps({
+  className
+}?: TooltipTriggerPropsArgs): TooltipPartProps;
+/** Popup prop bag: slot anchor plus the `data-open` visibility state. */
+declare function popupProps({
+  open,
+  className
+}?: TooltipPopupPropsArgs): TooltipPartProps;
+/** Arrow prop bag: just the slot anchor (the caret's side/align are runtime-stamped). */
+declare function arrowProps({
+  className
+}?: TooltipArrowPropsArgs): TooltipPartProps;
+//#endregion
+export { TooltipPartProps, TooltipPopupPropsArgs, arrowProps, popupProps, triggerProps };

package/dist/components/tooltip/tooltip.props.js

@@ -0,0 +1,42 @@
+import { TOOLTIP_SLOTS } from "./tooltip.slots.js";
+//#region src/components/tooltip/tooltip.props.ts
+/**
+* The D12 unified variant contract for Tooltip — a per-part set of `props(...)` builders that each
+* return a **spreadable props object** of the form `{ "data-slot": "noctis-tooltip-<part>",
+* ...dataAttrs }`, derived from the part's state inputs.
+*
+* Under the single-`data-slot` anchor model the `data-slot` is the only styling hook needed —
+* `tooltip.css` keys every rule off it — so spreading a part's `props()` onto a *foreign* element
+* styles it as that part:
+*
+*     <div {...Tooltip.Popup.props({ open: true })}>Saved</div>
+*     // → <div data-slot="noctis-tooltip-popup" data-open="">
+*
+* The escape hatch carries no className (styling is attribute-driven); an optional `className`
+* passthrough is accepted and forwarded verbatim. The same state→data-attribute mapping is emitted as
+* data from the token graph (`generated/declarations.json`) so non-React / agent consumers can
+* hand-write the markup from the docs.
+*/
+/** Stamp a boolean state as a bare data-attribute: present (`""`) when on, absent (`undefined`) when off. */
+const flag = (on) => on ? "" : void 0;
+const withClassName = (bag, className) => className === void 0 ? bag : {
+	...bag,
+	className
+};
+/** Trigger prop bag: just the slot anchor. */
+function triggerProps({ className } = {}) {
+	return withClassName({ "data-slot": TOOLTIP_SLOTS.trigger }, className);
+}
+/** Popup prop bag: slot anchor plus the `data-open` visibility state. */
+function popupProps({ open, className } = {}) {
+	return withClassName({
+		"data-slot": TOOLTIP_SLOTS.popup,
+		"data-open": flag(open)
+	}, className);
+}
+/** Arrow prop bag: just the slot anchor (the caret's side/align are runtime-stamped). */
+function arrowProps({ className } = {}) {
+	return withClassName({ "data-slot": TOOLTIP_SLOTS.arrow }, className);
+}
+//#endregion
+export { arrowProps, popupProps, triggerProps };

package/dist/components/tooltip/tooltip.slots.d.ts

@@ -0,0 +1,26 @@
+//#region src/components/tooltip/tooltip.slots.d.ts
+/**
+ * The `data-*` hooks `Tooltip` stamps on its parts, for host-side styling and tests. Slot values mark
+ * each rendered element; the state attributes are emitted by Base UI's Tooltip — pair a slot with a
+ * state to target, say, the popup only while it is animating in.
+ */
+declare enum TooltipDataAttributes {
+  /** The trigger element the tooltip is attached to. */
+  trigger = "data-slot",
+  /** Present on the popup while the tooltip is open. */
+  open = "data-open",
+  /** Present on the popup while the tooltip is closed (before it unmounts). */
+  closed = "data-closed",
+  /** The side of the trigger the popup actually rendered on (`top`, `bottom`, `inline-start`, …). */
+  side = "data-side",
+  /** How the popup is aligned along that side (`start`, `center`, `end`). */
+  align = "data-align",
+  /** 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 { TooltipDataAttributes };

package/dist/components/tooltip/tooltip.slots.js

@@ -0,0 +1,42 @@
+//#region src/components/tooltip/tooltip.slots.ts
+/**
+* The slot vocabulary every `Tooltip` part stamps as its `data-slot`. The authored source the
+* orchestration file reads from, prefixed `noctis-{component}-{part}` (the precompiled `tooltip.css`
+* keys every rule off these anchors); SLOTS.md still generates from the token-graph declarations.
+*
+* `positioner` and `arrow` are styling-only anchors (the z-index wrapper that stacks the bubble above
+* page chrome; the opt-in caret) — they carry no token mints, so they live here but not in the
+* token-graph anatomy, following the positioner precedent.
+*/
+const TOOLTIP_SLOTS = {
+	trigger: "noctis-tooltip-trigger",
+	positioner: "noctis-tooltip-positioner",
+	popup: "noctis-tooltip-popup",
+	arrow: "noctis-tooltip-arrow"
+};
+/**
+* The `data-*` hooks `Tooltip` stamps on its parts, for host-side styling and tests. Slot values mark
+* each rendered element; the state attributes are emitted by Base UI's Tooltip — pair a slot with a
+* state to target, say, the popup only while it is animating in.
+*/
+let TooltipDataAttributes = /* @__PURE__ */ function(TooltipDataAttributes) {
+	/** The trigger element the tooltip is attached to. */
+	TooltipDataAttributes["trigger"] = "data-slot";
+	/** Present on the popup while the tooltip is open. */
+	TooltipDataAttributes["open"] = "data-open";
+	/** Present on the popup while the tooltip is closed (before it unmounts). */
+	TooltipDataAttributes["closed"] = "data-closed";
+	/** The side of the trigger the popup actually rendered on (`top`, `bottom`, `inline-start`, …). */
+	TooltipDataAttributes["side"] = "data-side";
+	/** How the popup is aligned along that side (`start`, `center`, `end`). */
+	TooltipDataAttributes["align"] = "data-align";
+	/** Present on the popup for the first frame after mount — the transition's start state. */
+	TooltipDataAttributes["startingStyle"] = "data-starting-style";
+	/** Present on the popup while it transitions out before unmounting. */
+	TooltipDataAttributes["endingStyle"] = "data-ending-style";
+	/** Present on the popup when the change should not animate (focus open, dismissal). */
+	TooltipDataAttributes["instant"] = "data-instant";
+	return TooltipDataAttributes;
+}({});
+//#endregion
+export { TOOLTIP_SLOTS, TooltipDataAttributes };

package/dist/core/derive-threshold-tone.js

@@ -0,0 +1,35 @@
+//#region src/core/derive-threshold-tone.ts
+/** Clamp `n` into `[lo, hi]`. */
+function clamp(n, lo, hi) {
+	return Math.min(Math.max(n, lo), hi);
+}
+/**
+* Map a reading to its zone tone per the HTML `<meter>` rules. `low`/`high` default to `min`/`max`
+* and are clamped into a sane order; `value` is clamped to the range (mirroring how the bar fills).
+*
+* - `optimum <= low` — low is best (temperature, ping): `value <= low` → `success`; up to `high` →
+*   `warning`; above → `danger`.
+* - `optimum >= high` — high is best (battery, headroom): `value >= high` → `success`; down to `low` →
+*   `warning`; below → `danger`.
+* - `low < optimum < high` — the middle is best (tank pressure): inside `[low, high]` → `success`;
+*   outside → `warning` (never `danger`).
+*/
+function deriveThresholdTone({ value, min = 0, max = 100, low, high, optimum }) {
+	const lo = clamp(low ?? min, min, max);
+	const hi = clamp(high ?? max, lo, max);
+	const opt = clamp(optimum, min, max);
+	const reading = clamp(value, min, max);
+	if (opt <= lo) {
+		if (reading <= lo) return "success";
+		if (reading <= hi) return "warning";
+		return "danger";
+	}
+	if (opt >= hi) {
+		if (reading >= hi) return "success";
+		if (reading >= lo) return "warning";
+		return "danger";
+	}
+	return reading >= lo && reading <= hi ? "success" : "warning";
+}
+//#endregion
+export { deriveThresholdTone };

package/dist/core/merge-class-name.d.ts

@@ -0,0 +1,17 @@
+//#region src/core/merge-class-name.d.ts
+/**
+ * A Base UI `className` prop: a static string, or a function of the part's state. Base UI parts accept
+ * either form so a class can react to state (`open`, `disabled`, …); `State` is the part's state type.
+ */
+type ClassNameProp<State> = string | ((state: State) => string | undefined) | undefined;
+/**
+ * Merge a primitive's base classes with a consumer's `className`, preserving Base UI's state-function
+ * form: when the consumer passes a function, the result stays a function so it still receives the
+ * part's state; otherwise both collapse to a concatenated string via `clsx`. This is what lets a
+ * wrapped Base UI part keep the full styling API instead of narrowing `className` to a plain string.
+ * Bases are `data-slot`-keyed hand-authored CSS, not Tailwind utilities, so plain concatenation is
+ * correct — no `tailwind-merge` conflict resolution is needed in the framework-neutral core.
+ */
+declare function mergeClassName<State>(base: string, className: ClassNameProp<State>): ClassNameProp<State>;
+//#endregion
+export { ClassNameProp, mergeClassName };

package/dist/core/merge-class-name.js

@@ -0,0 +1,16 @@
+import clsx$1 from "clsx";
+//#region src/core/merge-class-name.ts
+/**
+* Merge a primitive's base classes with a consumer's `className`, preserving Base UI's state-function
+* form: when the consumer passes a function, the result stays a function so it still receives the
+* part's state; otherwise both collapse to a concatenated string via `clsx`. This is what lets a
+* wrapped Base UI part keep the full styling API instead of narrowing `className` to a plain string.
+* Bases are `data-slot`-keyed hand-authored CSS, not Tailwind utilities, so plain concatenation is
+* correct — no `tailwind-merge` conflict resolution is needed in the framework-neutral core.
+*/
+function mergeClassName(base, className) {
+	if (typeof className === "function") return (state) => clsx$1(base, className(state));
+	return clsx$1(base, className);
+}
+//#endregion
+export { mergeClassName };

package/dist/core/noctis-provider.d.ts

@@ -0,0 +1,38 @@
+import { ReactElement, ReactNode } from "react";
+import { LocalizedStrings, TextDirection } from "@stridge/noctis-intl/react";
+import { ThemeProviderProps } from "@stridge/noctis-design-tokens/react";
+
+//#region src/core/noctis-provider.d.ts
+/**
+ * The one provider for Noctis — composes the CSP nonce, locale/direction/labels, and the theme
+ * engine. Mount it once near the root. The contexts are independent and theme sits high, so
+ * everything beneath — including app-level providers — can read it. `theme` seeds the engine; omit
+ * it for the default theme. RTL-aware primitives resolve the active direction from Base UI's
+ * innermost `DirectionProvider`.
+ */
+declare function NoctisProvider({
+  locale,
+  direction,
+  messages,
+  theme,
+  themeOverrides,
+  nonce,
+  children
+}: NoctisProvider.Props): ReactElement;
+/**
+ * The provider's prop type. Types-only — it emits no runtime code and merges with the `NoctisProvider`
+ * function above, so `NoctisProvider` is the component value while `NoctisProvider.Props` is its prop type.
+ */
+declare namespace NoctisProvider {
+  type Props = {
+    /** The active BCP-47 locale. Required and controlled — the app (e.g. next-intl) is the source of truth. */locale: string; /** Reading direction. Defaults to the locale's via `isRTL`; pass it to override (e.g. a manual toggle). */
+    direction?: TextDirection; /** String dictionary for the localized-string hooks. Defaults to the built-in `en` stub. */
+    messages?: LocalizedStrings<string, string>; /** Server-resolved theme seed for the engine; omit it for the default theme. */
+    theme?: ThemeProviderProps["initialInput"]; /** Generation-time engine overrides — per-primitive replacements that participate in derivation. */
+    themeOverrides?: ThemeProviderProps["overrides"]; /** CSP nonce stamped on the inline styles Base UI injects, so they stay valid under a strict CSP. */
+    nonce?: string;
+    children: ReactNode;
+  };
+}
+//#endregion
+export { NoctisProvider };

package/dist/core/noctis-provider.js

@@ -0,0 +1,44 @@
+"use client";
+import { DEFAULT_MESSAGES } from "../i18n/default-messages.js";
+import { useMemo } from "react";
+import { jsx } from "react/jsx-runtime";
+import { LocaleContext, isRTL } from "@stridge/noctis-intl/react";
+import { DirectionProvider } from "@base-ui/react/direction-provider";
+import { CSPProvider } from "@base-ui/react/csp-provider";
+import { ThemeProvider } from "@stridge/noctis-design-tokens/react";
+//#region src/core/noctis-provider.tsx
+/**
+* The one provider for Noctis — composes the CSP nonce, locale/direction/labels, and the theme
+* engine. Mount it once near the root. The contexts are independent and theme sits high, so
+* everything beneath — including app-level providers — can read it. `theme` seeds the engine; omit
+* it for the default theme. RTL-aware primitives resolve the active direction from Base UI's
+* innermost `DirectionProvider`.
+*/
+function NoctisProvider({ locale, direction, messages, theme, themeOverrides, nonce, children }) {
+	const resolvedDirection = direction ?? (isRTL(locale) ? "rtl" : "ltr");
+	const value = useMemo(() => ({
+		locale,
+		direction: resolvedDirection,
+		dictionary: messages ?? DEFAULT_MESSAGES
+	}), [
+		locale,
+		resolvedDirection,
+		messages
+	]);
+	return /* @__PURE__ */ jsx(CSPProvider, {
+		nonce,
+		children: /* @__PURE__ */ jsx(ThemeProvider, {
+			initialInput: theme,
+			overrides: themeOverrides,
+			children: /* @__PURE__ */ jsx(LocaleContext.Provider, {
+				value,
+				children: /* @__PURE__ */ jsx(DirectionProvider, {
+					direction: resolvedDirection,
+					children
+				})
+			})
+		})
+	});
+}
+//#endregion
+export { NoctisProvider };

package/dist/core/primitive/index.d.ts

@@ -0,0 +1 @@
+import { Primitive } from "./primitive.js";

package/dist/core/primitive/primitive.d.ts

@@ -0,0 +1,44 @@
+import { useRender } from "../render.js";
+import { JSX, ReactElement, Ref } from "react";
+
+//#region src/core/primitive/primitive.d.ts
+interface PrimitiveOwnProps<TTag extends keyof JSX.IntrinsicElements = "div"> {
+  /** The HTML tag to render. Defaults to `div`. Use `render` to compose with a component instead. */
+  as?: TTag;
+  /** A Base UI render prop — an element or function — to replace the rendered element entirely. */
+  render?: useRender.RenderProp;
+  ref?: Ref<HTMLElement>;
+  /** The styling/testing hook attribute. Defaults to `noctis-primitive`. */
+  "data-slot"?: string;
+}
+/**
+ * The styled-element foundation every other primitive builds on: it renders any tag (`as`) or
+ * composes with another component (`render`), carries a `data-slot`, and forwards `className`
+ * verbatim so consumers can add their own classes. It is deliberately lean — only polymorphism and
+ * class passthrough — so layout and spacing concerns live on the primitives that own them, not on
+ * the base.
+ *
+ * @see {@link Primitive.Props}
+ */
+declare function Primitive<TTag extends keyof JSX.IntrinsicElements = "div">({
+  as,
+  render,
+  ref,
+  className,
+  "data-slot": dataSlot,
+  ...props
+}: Primitive.Props<TTag>): ReactElement;
+/**
+ * Prop types. Types-only — it emits no runtime code and merges with the `Primitive` function above,
+ * so `Primitive` is the component value while `Primitive.Props` is its prop type.
+ */
+declare namespace Primitive {
+  /**
+   * Props for `Primitive`, polymorphic over the rendered tag: the attributes track `as`, so
+   * `Primitive.Props<"a">` carries `href`/`target`, `Primitive.Props<"label">` carries `htmlFor`,
+   * and so on. Defaults to `"div"`.
+   */
+  type Props<TTag extends keyof JSX.IntrinsicElements = "div"> = PrimitiveOwnProps<TTag> & Omit<JSX.IntrinsicElements[TTag], keyof PrimitiveOwnProps<TTag>>;
+}
+//#endregion
+export { Primitive };