@stridge/noctis 1.0.0-beta.0

package/dist/components/rail/rail.js

@@ -0,0 +1,254 @@
+"use client";
+import { Icon } from "../../icons/icon.js";
+import { XIcon } from "../../icons/glyphs.js";
+import { useInjectedLabels } from "../../core/use-injected-labels.js";
+import { Surface } from "../surface/surface.js";
+import { Button } from "../button/button.js";
+import { collapsible_exports } from "../../primitives/collapsible.js";
+import { RailLayoutProvider, RailTitleProvider, useRailLayout, useRailTitleId } from "./rail.context.js";
+import { RAIL_SLOTS } from "./rail.slots.js";
+import { bodyProps, closeProps, contentProps, headerProps, layoutProps, panelProps, rootProps, surfaceProps, titleProps, triggerProps } from "./rail.props.js";
+import { useId } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/components/rail/rail.tsx
+/**
+* The translate distance for `push` — the rail's width, mapped from `RailSize`. The panel's own width
+* is the `--_rail-panel-width` token; the push translate lives on a sibling subtree the token's slot
+* doesn't reach, so it carries the same widths as a runtime var (`--rail-w`) here.
+*/
+const RAIL_WIDTH = {
+	xs: "14rem",
+	sm: "18rem",
+	md: "22rem",
+	lg: "28rem"
+};
+/**
+* Groups the parts and owns open state — controlled via `open`/`onOpenChange`, or uncontrolled via
+* `defaultOpen` — on Base UI's Collapsible. Unlike a modal sheet, the rail is non-modal: no backdrop,
+* no focus trap, no `Escape`-to-close. It renders transparently (`display: contents`) so the `Layout`
+* (or a lone `Panel`) becomes the surrounding layout's child directly.
+*
+* Slot: `noctis-rail`.
+* @see {@link Rail.Root.Props}
+*/
+function RailRoot({ className, ...props }) {
+	return /* @__PURE__ */ jsx(collapsible_exports.Collapsible.Root, {
+		"data-slot": RAIL_SLOTS.root,
+		className,
+		...props
+	});
+}
+/**
+* A button that toggles the rail. Base UI wires `aria-expanded` and `aria-controls` to the panel.
+*
+* Slot: `noctis-rail-trigger`.
+* @see {@link Rail.Trigger.Props}
+*/
+function RailTrigger({ className, ...props }) {
+	return /* @__PURE__ */ jsx(collapsible_exports.Collapsible.Trigger, {
+		"data-slot": RAIL_SLOTS.trigger,
+		className,
+		...props
+	});
+}
+/**
+* The docking row: lays the content and the rail side by side and sets the reflow `variant` so an
+* open rail reshapes the content beside it. Place a `Rail.Content` and a `Rail.Panel` inside. Use this
+* to dock a rail inside a region; drop a `Rail.Panel` on its own (no `Layout`) to dock it to the
+* viewport edge instead.
+*
+* Slot: `noctis-rail-layout`.
+* @see {@link Rail.Layout.Props}
+*/
+function RailLayout({ variant = "squeeze", side = "end", size = "md", className, style, ...props }) {
+	const railStyle = {
+		"--rail-w": RAIL_WIDTH[size],
+		...style
+	};
+	return /* @__PURE__ */ jsx(RailLayoutProvider, {
+		value: {
+			variant,
+			side,
+			size
+		},
+		children: /* @__PURE__ */ jsx("div", {
+			"data-slot": RAIL_SLOTS.layout,
+			"data-variant": variant,
+			className,
+			style: railStyle,
+			...props
+		})
+	});
+}
+/**
+* The content beside the rail inside a `Rail.Layout`. Reshapes per the layout's `variant` when open.
+*
+* Slot: `noctis-rail-content`.
+* @see {@link Rail.Content.Props}
+*/
+function RailContent({ className, ...props }) {
+	const layout = useRailLayout();
+	return /* @__PURE__ */ jsx("div", {
+		"data-slot": RAIL_SLOTS.content,
+		"data-variant": layout?.variant ?? "squeeze",
+		"data-side": layout?.side ?? "end",
+		className,
+		...props
+	});
+}
+/**
+* The docked rail itself: a `Collapsible.Panel` rendered as an `aside` (a complementary landmark).
+* Kept mounted while closed and hidden via Base UI, so it leaves the layout and the a11y tree without
+* losing its content. Drop `Rail.Header`/`Rail.Body` inside; a `Rail.Title` names it automatically via
+* `aria-labelledby`. Inside a `Rail.Layout` it docks in that layout's cell; on its own it docks to the
+* viewport edge. `side`/`size` default to the surrounding `Rail.Layout`'s.
+*
+* Slots: `noctis-rail-panel` (the collapsible), `noctis-rail-surface` (the inner surface).
+* @see {@link Rail.Panel.Props}
+*/
+function RailPanel({ side, size, keepMounted = true, className, children, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledby, ...props }) {
+	const layout = useRailLayout();
+	const titleId = useId();
+	const resolvedSide = side ?? layout?.side ?? "end";
+	const resolvedSize = size ?? layout?.size ?? "md";
+	const docking = layout ? "inline" : "dock";
+	return /* @__PURE__ */ jsx(RailTitleProvider, {
+		value: titleId,
+		children: /* @__PURE__ */ jsx(collapsible_exports.Collapsible.Panel, {
+			"data-slot": RAIL_SLOTS.panel,
+			"data-docking": docking,
+			"data-variant": layout?.variant ?? "squeeze",
+			"data-side": resolvedSide,
+			"data-size": resolvedSize,
+			keepMounted,
+			"aria-label": ariaLabel,
+			"aria-labelledby": ariaLabelledby ?? (ariaLabel ? void 0 : titleId),
+			className,
+			render: /* @__PURE__ */ jsx("aside", {}),
+			...props,
+			children: /* @__PURE__ */ jsx(Surface, {
+				"data-slot": RAIL_SLOTS.surface,
+				"data-side": resolvedSide,
+				children
+			})
+		})
+	});
+}
+/** English fallbacks and catalog keys for the close button's accessible name (resolved per active locale). */
+const DEFAULT_CLOSE_LABELS = { close: "Close" };
+const CLOSE_LABEL_KEYS = { close: "rail.closeLabel" };
+/**
+* A ghost icon button that closes the rail. Defaults its glyph to a lucide `X` and its name to the
+* translated "Close"; pass `children` to swap the glyph or `aria-label` to override the name.
+*
+* Slot: `noctis-rail-close`.
+* @see {@link Rail.Close.Props}
+*/
+function RailClose({ className, children, "aria-label": ariaLabel, ...props }) {
+	const labels = useInjectedLabels(DEFAULT_CLOSE_LABELS, CLOSE_LABEL_KEYS, void 0);
+	return /* @__PURE__ */ jsx(collapsible_exports.Collapsible.Trigger, {
+		...Button.props({
+			variant: "ghost",
+			iconOnly: true
+		}),
+		"data-slot": RAIL_SLOTS.close,
+		"aria-label": ariaLabel ?? labels.close,
+		className,
+		...props,
+		children: children ?? /* @__PURE__ */ jsx(Icon, {
+			icon: XIcon,
+			size: "sm"
+		})
+	});
+}
+/**
+* The rail's top region — title and corner actions. Separated by a divider.
+*
+* Slot: `noctis-rail-header`.
+* @see {@link Rail.Header.Props}
+*/
+function RailHeader({ className, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		"data-slot": RAIL_SLOTS.header,
+		className,
+		...props
+	});
+}
+/**
+* The scrollable middle region. Grows to fill and scrolls its overflow so the header stays put.
+*
+* Slot: `noctis-rail-body`.
+* @see {@link Rail.Body.Props}
+*/
+function RailBody({ className, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		"data-slot": RAIL_SLOTS.body,
+		className,
+		...props
+	});
+}
+/**
+* The accessible name of the rail, linked to the panel via `aria-labelledby`. Renders an `<h2>`.
+*
+* Slot: `noctis-rail-title`.
+* @see {@link Rail.Title.Props}
+*/
+function RailTitle({ className, children, ...props }) {
+	const titleId = useRailTitleId();
+	return /* @__PURE__ */ jsx("h2", {
+		"data-slot": RAIL_SLOTS.title,
+		className,
+		...props,
+		id: titleId ?? void 0,
+		children
+	});
+}
+/**
+* A docked, collapsible side rail — a non-modal panel that lives in the layout rather than over it.
+*
+* **Rail vs. Sheet.** Reach for a `Sheet` when the panel is a *modal task*: it overlays the page on a
+* dimmed backdrop, traps focus, and closes on `Escape`/outside-click — the page behind is inert until
+* it's dismissed. Reach for a `Rail` when the panel is a *persistent companion* to the page (an
+* inspector, a filter rail, a settings panel): it docks beside the content and **reshapes** it instead
+* of covering it, so the page stays fully usable with the rail open. No backdrop, no focus trap, no
+* `Escape`-to-close.
+*
+* **Two reflow variants** (set on {@link Rail.Layout}): `squeeze` shrinks the content's width so it
+* re-lays-out into the narrower space; `push` keeps the content's width and slides it over, clipping
+* the overflow. Both keep the content interactive — that's the line between a rail and a sheet.
+*
+* **Docking.** Wrap a `Rail.Content` and a `Rail.Panel` in a `Rail.Layout` to dock the rail inside a
+* region. Or drop a `Rail.Panel` straight into the page (no `Layout`) to dock it full-height to the
+* viewport edge — reflowing on large screens, overlaying the edge on small ones.
+*
+* Compose it from parts: `Rail.Root` owns state, `Rail.Trigger` toggles it, `Rail.Layout` +
+* `Rail.Content` set up the reflow, and `Rail.Panel` holds `Header`/`Body`, `Title`, and `Close`.
+*
+* Built on Base UI's Collapsible for the open/close behavior, measured-size animation, and a11y; the
+* runtime compound is a plain object (kept tree-shakeable), with per-part prop types exposed through
+* the matching `Rail` namespace below — e.g. `Rail.Panel.Props`.
+*/
+const Rail = {
+	/** Groups the parts and owns open state. `Rail.Root.props()` → its spreadable prop bag. */
+	Root: Object.assign(RailRoot, { props: rootProps }),
+	/** Toggles the rail. `Rail.Trigger.props()` → its spreadable prop bag. */
+	Trigger: Object.assign(RailTrigger, { props: triggerProps }),
+	/** The docking row. `Rail.Layout.props({ variant })` → its spreadable prop bag. */
+	Layout: Object.assign(RailLayout, { props: layoutProps }),
+	/** The content beside the rail. `Rail.Content.props({ variant, side })` → its spreadable prop bag. */
+	Content: Object.assign(RailContent, { props: contentProps }),
+	/** The docked rail. `Rail.Panel.props({ docking, variant, side, size })` → its spreadable prop bag. */
+	Panel: Object.assign(RailPanel, { props: panelProps }),
+	/** The ghost-icon close button. `Rail.Close.props()` → its spreadable prop bag. */
+	Close: Object.assign(RailClose, { props: closeProps }),
+	/** The header region. `Rail.Header.props()` → its spreadable prop bag. */
+	Header: Object.assign(RailHeader, { props: headerProps }),
+	/** The scrollable body. `Rail.Body.props()` → its spreadable prop bag. */
+	Body: Object.assign(RailBody, { props: bodyProps }),
+	/** The accessible name. `Rail.Title.props()` → its spreadable prop bag. */
+	Title: Object.assign(RailTitle, { props: titleProps }),
+	/** The inner surface escape-hatch. `Rail.Surface.props({ side })` → its spreadable prop bag. */
+	Surface: { props: surfaceProps }
+};
+//#endregion
+export { Rail };

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

@@ -0,0 +1,98 @@
+import { RailSide, RailSize, RailVariant } from "./rail.context.js";
+
+//#region src/components/rail/rail.props.d.ts
+/** A spreadable data-attribute prop bag — the shape every `Rail.*.props()` returns. */
+type RailPartProps = {
+  /** The slot value the matching `rail.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 (a value) 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 `Rail.Root.props(...)` — the contents-root that carries the `--_rail-padding` scope. */
+type RailRootPropsArgs = BasePropsArgs;
+/** Argument to `Rail.Trigger.props(...)` — slot-only; toggles the rail. */
+type RailTriggerPropsArgs = BasePropsArgs;
+/** Argument to `Rail.Layout.props(...)` — the docking row; `variant` drives the push-clip overflow. */
+interface RailLayoutPropsArgs extends BasePropsArgs {
+  /** How an open rail reshapes the content. @default "squeeze" */
+  variant?: RailVariant;
+}
+/** Argument to `Rail.Content.props(...)` — the region beside the rail; `variant`/`side` drive its reflow. */
+interface RailContentPropsArgs extends BasePropsArgs {
+  /** How an open rail reshapes this content. @default "squeeze" */
+  variant?: RailVariant;
+  /** Which edge the rail docks to (the push slide direction). @default "end" */
+  side?: RailSide;
+}
+/** Argument to `Rail.Panel.props(...)` — the collapsible; carries docking mode, reflow, side, and size. */
+interface RailPanelPropsArgs extends BasePropsArgs {
+  /** Standalone (viewport-edge) vs in-layout docking. @default "dock" */
+  docking?: "dock" | "inline";
+  /** The surrounding layout's reflow mode (only meaningful for `inline` docking). @default "squeeze" */
+  variant?: RailVariant;
+  /** Which edge the rail docks to. @default "end" */
+  side?: RailSide;
+  /** The rail's width — re-points the `--_rail-panel-width` token. @default "md" */
+  size?: RailSize;
+}
+/** Argument to `Rail.Surface.props(...)` — the inner surface; `side` draws the divider toward the content. */
+interface RailSurfacePropsArgs extends BasePropsArgs {
+  /** Which edge the rail docks to (the divider faces the content). @default "end" */
+  side?: RailSide;
+}
+/** Argument to a stateless part's `.props(...)` — no recipe of its own; look flows from its own slot. */
+type RailStatelessPropsArgs = BasePropsArgs;
+/** Root prop bag: the contents-root slot anchor (also the `--_rail-padding` scope). */
+declare function rootProps({
+  className
+}?: RailRootPropsArgs): RailPartProps;
+/** Trigger prop bag: just the slot anchor. */
+declare function triggerProps({
+  className
+}?: RailTriggerPropsArgs): RailPartProps;
+/** Layout prop bag: slot anchor plus the `data-variant` the push-clip overflow keys off. */
+declare function layoutProps({
+  variant,
+  className
+}?: RailLayoutPropsArgs): RailPartProps;
+/** Content prop bag: slot anchor plus the `data-variant`/`data-side` the reflow + push slide read. */
+declare function contentProps({
+  variant,
+  side,
+  className
+}?: RailContentPropsArgs): RailPartProps;
+/** Panel prop bag: slot anchor plus the `data-docking`/`data-variant`/`data-side`/`data-size` recipe. */
+declare function panelProps({
+  docking,
+  variant,
+  side,
+  size,
+  className
+}?: RailPanelPropsArgs): RailPartProps;
+/** Surface prop bag: slot anchor plus the `data-side` the divider edge keys off. */
+declare function surfaceProps({
+  side,
+  className
+}?: RailSurfacePropsArgs): RailPartProps;
+/** Close prop bag: just the slot anchor (its ghost-icon look comes from the composed `Button.props`). */
+declare function closeProps({
+  className
+}?: RailStatelessPropsArgs): RailPartProps;
+/** Header prop bag: just the slot anchor. */
+declare function headerProps({
+  className
+}?: RailStatelessPropsArgs): RailPartProps;
+/** Body prop bag: just the slot anchor. */
+declare function bodyProps({
+  className
+}?: RailStatelessPropsArgs): RailPartProps;
+/** Title prop bag: just the slot anchor. */
+declare function titleProps({
+  className
+}?: RailStatelessPropsArgs): RailPartProps;
+//#endregion
+export { RailPartProps, bodyProps, closeProps, contentProps, headerProps, layoutProps, panelProps, rootProps, surfaceProps, titleProps, triggerProps };

package/dist/components/rail/rail.props.js

@@ -0,0 +1,64 @@
+import { RAIL_SLOTS } from "./rail.slots.js";
+//#region src/components/rail/rail.props.ts
+const withClassName = (bag, className) => className === void 0 ? bag : {
+	...bag,
+	className
+};
+/** Root prop bag: the contents-root slot anchor (also the `--_rail-padding` scope). */
+function rootProps({ className } = {}) {
+	return withClassName({ "data-slot": RAIL_SLOTS.root }, className);
+}
+/** Trigger prop bag: just the slot anchor. */
+function triggerProps({ className } = {}) {
+	return withClassName({ "data-slot": RAIL_SLOTS.trigger }, className);
+}
+/** Layout prop bag: slot anchor plus the `data-variant` the push-clip overflow keys off. */
+function layoutProps({ variant = "squeeze", className } = {}) {
+	return withClassName({
+		"data-slot": RAIL_SLOTS.layout,
+		"data-variant": variant
+	}, className);
+}
+/** Content prop bag: slot anchor plus the `data-variant`/`data-side` the reflow + push slide read. */
+function contentProps({ variant = "squeeze", side = "end", className } = {}) {
+	return withClassName({
+		"data-slot": RAIL_SLOTS.content,
+		"data-variant": variant,
+		"data-side": side
+	}, className);
+}
+/** Panel prop bag: slot anchor plus the `data-docking`/`data-variant`/`data-side`/`data-size` recipe. */
+function panelProps({ docking = "dock", variant = "squeeze", side = "end", size = "md", className } = {}) {
+	return withClassName({
+		"data-slot": RAIL_SLOTS.panel,
+		"data-docking": docking,
+		"data-variant": variant,
+		"data-side": side,
+		"data-size": size
+	}, className);
+}
+/** Surface prop bag: slot anchor plus the `data-side` the divider edge keys off. */
+function surfaceProps({ side = "end", className } = {}) {
+	return withClassName({
+		"data-slot": RAIL_SLOTS.surface,
+		"data-side": side
+	}, className);
+}
+/** Close prop bag: just the slot anchor (its ghost-icon look comes from the composed `Button.props`). */
+function closeProps({ className } = {}) {
+	return withClassName({ "data-slot": RAIL_SLOTS.close }, className);
+}
+/** Header prop bag: just the slot anchor. */
+function headerProps({ className } = {}) {
+	return withClassName({ "data-slot": RAIL_SLOTS.header }, className);
+}
+/** Body prop bag: just the slot anchor. */
+function bodyProps({ className } = {}) {
+	return withClassName({ "data-slot": RAIL_SLOTS.body }, className);
+}
+/** Title prop bag: just the slot anchor. */
+function titleProps({ className } = {}) {
+	return withClassName({ "data-slot": RAIL_SLOTS.title }, className);
+}
+//#endregion
+export { bodyProps, closeProps, contentProps, headerProps, layoutProps, panelProps, rootProps, surfaceProps, titleProps, triggerProps };

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

@@ -0,0 +1,20 @@
+//#region src/components/rail/rail.slots.d.ts
+/**
+ * The data attributes `Rail`'s parts expose for styling and testing. Each member's value is the
+ * attribute name and its JSDoc is the description; the docs API reference reads this enum directly, so
+ * the documented attributes can't drift from the precompiled `rail.css` rules that key off them.
+ */
+declare enum RailDataAttributes {
+  /** The catalog slot that anchors every `rail.css` rule and marks the part for SLOTS.md/testing. */
+  slot = "data-slot",
+  /** The reflow mode — `squeeze` | `push` — on the layout/content/panel; drives clip/slide/float. */
+  variant = "data-variant",
+  /** Which edge the rail docks to — `start` | `end`; drives the divider edge and the slide direction. */
+  side = "data-side",
+  /** The rail's width — `xs` | `sm` | `md` | `lg`; the generated layer keys the width token off it. */
+  size = "data-size",
+  /** Standalone vs in-layout docking — `dock` | `inline`; selects the viewport-edge vs cell rules. */
+  docking = "data-docking"
+}
+//#endregion
+export { RailDataAttributes };

package/dist/components/rail/rail.slots.js

@@ -0,0 +1,40 @@
+//#region src/components/rail/rail.slots.ts
+/**
+* The slot vocabulary every `Rail` part stamps as its `data-slot`. The authored source the
+* orchestration file reads from, kebab-cased `{component}[-{part}]` under the `noctis-` prefix; SLOTS.md
+* still generates from the token-graph declarations. `Rail.Root` renders a `display: contents` element
+* carrying the bare `noctis-rail` slot, and `Rail.Panel` stamps two — `noctis-rail-panel` on the
+* collapsible and `noctis-rail-surface` on the inner surface.
+*/
+const RAIL_SLOTS = {
+	root: "noctis-rail",
+	trigger: "noctis-rail-trigger",
+	layout: "noctis-rail-layout",
+	content: "noctis-rail-content",
+	panel: "noctis-rail-panel",
+	surface: "noctis-rail-surface",
+	close: "noctis-rail-close",
+	header: "noctis-rail-header",
+	body: "noctis-rail-body",
+	title: "noctis-rail-title"
+};
+/**
+* The data attributes `Rail`'s parts expose for styling and testing. Each member's value is the
+* attribute name and its JSDoc is the description; the docs API reference reads this enum directly, so
+* the documented attributes can't drift from the precompiled `rail.css` rules that key off them.
+*/
+let RailDataAttributes = /* @__PURE__ */ function(RailDataAttributes) {
+	/** The catalog slot that anchors every `rail.css` rule and marks the part for SLOTS.md/testing. */
+	RailDataAttributes["slot"] = "data-slot";
+	/** The reflow mode — `squeeze` | `push` — on the layout/content/panel; drives clip/slide/float. */
+	RailDataAttributes["variant"] = "data-variant";
+	/** Which edge the rail docks to — `start` | `end`; drives the divider edge and the slide direction. */
+	RailDataAttributes["side"] = "data-side";
+	/** The rail's width — `xs` | `sm` | `md` | `lg`; the generated layer keys the width token off it. */
+	RailDataAttributes["size"] = "data-size";
+	/** Standalone vs in-layout docking — `dock` | `inline`; selects the viewport-edge vs cell rules. */
+	RailDataAttributes["docking"] = "data-docking";
+	return RailDataAttributes;
+}({});
+//#endregion
+export { RAIL_SLOTS, RailDataAttributes };

package/dist/components/scroll-area/index.d.ts

@@ -0,0 +1,2 @@
+import { ScrollArea } from "./scroll-area.js";
+import { ScrollAreaDataAttributes } from "./scroll-area.slots.js";

package/dist/components/scroll-area/scroll-area.context.js

@@ -0,0 +1,15 @@
+"use client";
+import { createContext, use } from "react";
+//#region src/components/scroll-area/scroll-area.context.ts
+const ScrollAreaContext = createContext(null);
+/** Provides the root's visibility policy to the scrollbars beneath it. */
+const ScrollAreaProvider = ScrollAreaContext.Provider;
+/**
+* Read the scroll-area context, or `null` when a part renders standalone (outside `ScrollArea.Root`)
+* — the scrollbar stays usable on its own, it just can't auto-derive `keepMounted` from the policy.
+*/
+function useScrollAreaContext() {
+	return use(ScrollAreaContext);
+}
+//#endregion
+export { ScrollAreaProvider, useScrollAreaContext };