@ttoss/fsl-ui 0.2.4 → 0.2.5

package/dist/components/NumberField/NumberField.mjs

@@ -3,8 +3,8 @@ import { focusRingOutline } from "../../tokens/focusRing.mjs";
 import { resolveInteractiveStyle } from "../../tokens/resolveInteractiveStyle.mjs";
 import { Icon } from "../Icon/Icon.mjs";
 import { vars } from "@ttoss/fsl-theme/vars";
-import { Button, FieldError, Group, Input, Label, NumberField, Text } from "react-aria-components";
 import { jsx, jsxs } from "react/jsx-runtime";
+import { Button, FieldError, Group, Input, Label, NumberField, Text } from "react-aria-components";
 
 //#region src/components/NumberField/NumberField.tsx
 /** Formal semantic identity — NumberField root (Input entity). */
@@ -24,7 +24,7 @@ var buildControlBoxStyle = ({
     boxSizing: "border-box",
     display: "inline-flex",
     alignItems: "center",
-    minHeight: vars.sizing.hit.base,
+    minHeight: vars.sizing.hit,
     borderRadius: vars.radii.control,
     borderWidth: vars.border.outline.control.width,
     borderStyle: vars.border.outline.control.style,

package/dist/components/ProgressBar/ProgressBar.cjs

@@ -2,8 +2,8 @@
 const require_runtime = require('../../_virtual/_rolldown/runtime.cjs');
 const require_keyframes = require('../../tokens/keyframes.cjs');
 let _ttoss_fsl_theme_vars = require("@ttoss/fsl-theme/vars");
-let react_aria_components = require("react-aria-components");
 let react_jsx_runtime = require("react/jsx-runtime");
+let react_aria_components = require("react-aria-components");
 let react = require("react");
 react = require_runtime.__toESM(react);
 

package/dist/components/ProgressBar/ProgressBar.mjs

@@ -1,8 +1,8 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
 import { ANIMATION_NAMES, ensureKeyframes } from "../../tokens/keyframes.mjs";
 import { vars } from "@ttoss/fsl-theme/vars";
-import { ProgressBar } from "react-aria-components";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { ProgressBar } from "react-aria-components";
 import * as React from "react";
 
 //#region src/components/ProgressBar/ProgressBar.tsx

package/dist/components/RadioGroup/RadioGroup.cjs

@@ -2,8 +2,8 @@
 const require_focusRing = require('../../tokens/focusRing.cjs');
 const require_resolveInteractiveStyle = require('../../tokens/resolveInteractiveStyle.cjs');
 let _ttoss_fsl_theme_vars = require("@ttoss/fsl-theme/vars");
-let react_aria_components = require("react-aria-components");
 let react_jsx_runtime = require("react/jsx-runtime");
+let react_aria_components = require("react-aria-components");
 
 //#region src/components/RadioGroup/RadioGroup.tsx
 /** Formal semantic identity — RadioGroup root (Selection entity, single-choice). */
@@ -151,7 +151,7 @@ var Radio = ({
         display: "inline-flex",
         alignItems: "center",
         gap: _ttoss_fsl_theme_vars.vars.spacing.gap.inline.sm,
-        minHeight: _ttoss_fsl_theme_vars.vars.sizing.hit.base,
+        minHeight: _ttoss_fsl_theme_vars.vars.sizing.hit,
         cursor: isDisabled ? "not-allowed" : "pointer",
         opacity: isDisabled ? _ttoss_fsl_theme_vars.vars.opacity.disabled : void 0,
         ..._ttoss_fsl_theme_vars.vars.text.label.md,

package/dist/components/RadioGroup/RadioGroup.mjs

@@ -2,8 +2,8 @@
 import { focusRingOutline } from "../../tokens/focusRing.mjs";
 import { resolveInteractiveStyle } from "../../tokens/resolveInteractiveStyle.mjs";
 import { vars } from "@ttoss/fsl-theme/vars";
-import { Label, Radio, RadioGroup } from "react-aria-components";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { Label, Radio, RadioGroup } from "react-aria-components";
 
 //#region src/components/RadioGroup/RadioGroup.tsx
 /** Formal semantic identity — RadioGroup root (Selection entity, single-choice). */
@@ -151,7 +151,7 @@ var Radio$1 = ({
         display: "inline-flex",
         alignItems: "center",
         gap: vars.spacing.gap.inline.sm,
-        minHeight: vars.sizing.hit.base,
+        minHeight: vars.sizing.hit,
         cursor: isDisabled ? "not-allowed" : "pointer",
         opacity: isDisabled ? vars.opacity.disabled : void 0,
         ...vars.text.label.md,

package/dist/components/Select/Select.cjs

@@ -3,8 +3,8 @@ const require_focusRing = require('../../tokens/focusRing.cjs');
 const require_resolveInteractiveStyle = require('../../tokens/resolveInteractiveStyle.cjs');
 const require_Icon = require('../Icon/Icon.cjs');
 let _ttoss_fsl_theme_vars = require("@ttoss/fsl-theme/vars");
-let react_aria_components = require("react-aria-components");
 let react_jsx_runtime = require("react/jsx-runtime");
+let react_aria_components = require("react-aria-components");
 
 //#region src/components/Select/Select.tsx
 var selectMeta = {
@@ -104,7 +104,7 @@ var Select = ({
               alignItems: "center",
               justifyContent: "space-between",
               gap: _ttoss_fsl_theme_vars.vars.spacing.gap.inline.sm,
-              minHeight: _ttoss_fsl_theme_vars.vars.sizing.hit.base,
+              minHeight: _ttoss_fsl_theme_vars.vars.sizing.hit,
               paddingBlock: _ttoss_fsl_theme_vars.vars.spacing.inset.control.md,
               paddingInline: _ttoss_fsl_theme_vars.vars.spacing.inset.control.md,
               borderRadius: _ttoss_fsl_theme_vars.vars.radii.control,

package/dist/components/Select/Select.mjs

@@ -3,8 +3,8 @@ import { focusRingOutline } from "../../tokens/focusRing.mjs";
 import { resolveInteractiveStyle } from "../../tokens/resolveInteractiveStyle.mjs";
 import { Icon } from "../Icon/Icon.mjs";
 import { vars } from "@ttoss/fsl-theme/vars";
-import { Button, Label, ListBox, ListBoxItem, Popover, Select, SelectValue } from "react-aria-components";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { Button, Label, ListBox, ListBoxItem, Popover, Select, SelectValue } from "react-aria-components";
 
 //#region src/components/Select/Select.tsx
 var selectMeta = {
@@ -104,7 +104,7 @@ var Select$1 = ({
               alignItems: "center",
               justifyContent: "space-between",
               gap: vars.spacing.gap.inline.sm,
-              minHeight: vars.sizing.hit.base,
+              minHeight: vars.sizing.hit,
               paddingBlock: vars.spacing.inset.control.md,
               paddingInline: vars.spacing.inset.control.md,
               borderRadius: vars.radii.control,

package/dist/components/Separator/Separator.cjs

@@ -1,7 +1,7 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
 let _ttoss_fsl_theme_vars = require("@ttoss/fsl-theme/vars");
-let react_aria_components = require("react-aria-components");
 let react_jsx_runtime = require("react/jsx-runtime");
+let react_aria_components = require("react-aria-components");
 
 //#region src/components/Separator/Separator.tsx
 /** Formal semantic identity — Separator root (Structure entity, divider). */

package/dist/components/Separator/Separator.mjs

@@ -1,7 +1,7 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
 import { vars } from "@ttoss/fsl-theme/vars";
-import { Separator } from "react-aria-components";
 import { jsx } from "react/jsx-runtime";
+import { Separator } from "react-aria-components";
 
 //#region src/components/Separator/Separator.tsx
 /** Formal semantic identity — Separator root (Structure entity, divider). */

package/dist/components/Slider/Slider.cjs

@@ -1,8 +1,8 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
 const require_focusRing = require('../../tokens/focusRing.cjs');
 let _ttoss_fsl_theme_vars = require("@ttoss/fsl-theme/vars");
-let react_aria_components = require("react-aria-components");
 let react_jsx_runtime = require("react/jsx-runtime");
+let react_aria_components = require("react-aria-components");
 
 //#region src/components/Slider/Slider.tsx
 /** Formal semantic identity — Slider root (Input entity). */

package/dist/components/Slider/Slider.mjs

@@ -1,8 +1,8 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
 import { focusRingOutline } from "../../tokens/focusRing.mjs";
 import { vars } from "@ttoss/fsl-theme/vars";
-import { Label, Slider, SliderOutput, SliderThumb, SliderTrack } from "react-aria-components";
 import { jsx, jsxs } from "react/jsx-runtime";
+import { Label, Slider, SliderOutput, SliderThumb, SliderTrack } from "react-aria-components";
 
 //#region src/components/Slider/Slider.tsx
 /** Formal semantic identity — Slider root (Input entity). */

package/dist/components/Stack/Stack.cjs

@@ -0,0 +1,89 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+let _ttoss_fsl_theme_vars = require("@ttoss/fsl-theme/vars");
+let react_jsx_runtime = require("react/jsx-runtime");
+
+//#region src/components/Stack/Stack.tsx
+/** Formal semantic identity — Stack root (Structure entity, layout rhythm). */
+var stackMeta = {
+  displayName: "Stack",
+  entity: "Structure",
+  structure: "root"
+};
+var GAP_STACK = {
+  xs: _ttoss_fsl_theme_vars.vars.spacing.gap.stack.xs,
+  sm: _ttoss_fsl_theme_vars.vars.spacing.gap.stack.sm,
+  md: _ttoss_fsl_theme_vars.vars.spacing.gap.stack.md,
+  lg: _ttoss_fsl_theme_vars.vars.spacing.gap.stack.lg,
+  xl: _ttoss_fsl_theme_vars.vars.spacing.gap.stack.xl
+};
+var GAP_INLINE = {
+  xs: _ttoss_fsl_theme_vars.vars.spacing.gap.inline.xs,
+  sm: _ttoss_fsl_theme_vars.vars.spacing.gap.inline.sm,
+  md: _ttoss_fsl_theme_vars.vars.spacing.gap.inline.md,
+  lg: _ttoss_fsl_theme_vars.vars.spacing.gap.inline.lg,
+  xl: _ttoss_fsl_theme_vars.vars.spacing.gap.inline.xl
+};
+var ALIGN = {
+  start: "flex-start",
+  center: "center",
+  end: "flex-end",
+  stretch: "stretch"
+};
+var JUSTIFY = {
+  start: "flex-start",
+  center: "center",
+  end: "flex-end",
+  between: "space-between"
+};
+/**
+* The layout rhythm primitive — a flex container spaced from the FSL gap scale.
+*
+* Entity = Structure. Use it to stack sections (`direction="vertical"`) or lay
+* out a row of controls (`direction="horizontal"`) with consistent, themeable
+* spacing. `gap`, `align`, and `justify` draw only from named scales/keywords —
+* there is no raw `gap: 12px`, which is how spacing rhythm stays consistent
+* across a product.
+*
+* @example
+* ```tsx
+* <Stack gap="lg">
+*   <Heading level={2}>Payment</Heading>
+*   <Stack direction="horizontal" gap="sm" justify="end">
+*     <Button evaluation="muted">Cancel</Button>
+*     <Button evaluation="primary">Save</Button>
+*   </Stack>
+* </Stack>
+* ```
+*/
+var Stack = ({
+  direction = "vertical",
+  gap = "md",
+  align = "stretch",
+  justify = "start",
+  wrap = false,
+  children,
+  ...props
+}) => {
+  const isHorizontal = direction === "horizontal";
+  return /* @__PURE__ */(0, react_jsx_runtime.jsx)("div", {
+    ...props,
+    "data-scope": "stack",
+    "data-part": "root",
+    "data-direction": direction,
+    "data-gap": gap,
+    style: {
+      display: "flex",
+      flexDirection: isHorizontal ? "row" : "column",
+      gap: isHorizontal ? GAP_INLINE[gap] : GAP_STACK[gap],
+      alignItems: ALIGN[align],
+      justifyContent: JUSTIFY[justify],
+      flexWrap: wrap ? "wrap" : "nowrap"
+    },
+    children
+  });
+};
+Stack.displayName = stackMeta.displayName;
+
+//#endregion
+exports.Stack = Stack;
+exports.stackMeta = stackMeta;

package/dist/components/Stack/Stack.d.cts

@@ -0,0 +1,75 @@
+
+import * as React from "react";
+
+//#region src/components/Stack/Stack.d.ts
+/** Formal semantic identity — Stack root (Structure entity, layout rhythm). */
+declare const stackMeta: {
+  readonly displayName: "Stack";
+  readonly entity: "Structure";
+  readonly structure: "root";
+};
+/** Flow direction — vertical stacks, horizontal inlines. */
+type StackDirection = 'vertical' | 'horizontal';
+/** A step of the gap scale. */
+type StackGap = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+/** Cross-axis alignment. */
+type StackAlign = 'start' | 'center' | 'end' | 'stretch';
+/** Main-axis distribution. */
+type StackJustify = 'start' | 'center' | 'end' | 'between';
+/** Props for the Stack component. */
+interface StackProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'style' | 'className'> {
+  /**
+   * Flow direction. `vertical` stacks children in a column (reads the
+   * `gap.stack` scale); `horizontal` lays them in a row (reads `gap.inline`).
+   * @default 'vertical'
+   */
+  direction?: StackDirection;
+  /**
+   * Space between children, from the gap scale. There is no raw-length
+   * vocabulary — rhythm always comes from the scale.
+   * @default 'md'
+   */
+  gap?: StackGap;
+  /** Cross-axis alignment (`align-items`). @default 'stretch' */
+  align?: StackAlign;
+  /** Main-axis distribution (`justify-content`). @default 'start' */
+  justify?: StackJustify;
+  /** Allow children to wrap onto multiple lines. @default false */
+  wrap?: boolean;
+  /** The items to lay out. */
+  children?: React.ReactNode;
+}
+/**
+ * The layout rhythm primitive — a flex container spaced from the FSL gap scale.
+ *
+ * Entity = Structure. Use it to stack sections (`direction="vertical"`) or lay
+ * out a row of controls (`direction="horizontal"`) with consistent, themeable
+ * spacing. `gap`, `align`, and `justify` draw only from named scales/keywords —
+ * there is no raw `gap: 12px`, which is how spacing rhythm stays consistent
+ * across a product.
+ *
+ * @example
+ * ```tsx
+ * <Stack gap="lg">
+ *   <Heading level={2}>Payment</Heading>
+ *   <Stack direction="horizontal" gap="sm" justify="end">
+ *     <Button evaluation="muted">Cancel</Button>
+ *     <Button evaluation="primary">Save</Button>
+ *   </Stack>
+ * </Stack>
+ * ```
+ */
+declare const Stack: {
+  ({
+    direction,
+    gap,
+    align,
+    justify,
+    wrap,
+    children,
+    ...props
+  }: StackProps): import("react/jsx-runtime").JSX.Element;
+  displayName: "Stack";
+};
+//#endregion
+export { Stack, StackAlign, StackDirection, StackGap, StackJustify, StackProps, stackMeta };

package/dist/components/Stack/Stack.d.mts

@@ -0,0 +1,75 @@
+
+import * as React from "react";
+
+//#region src/components/Stack/Stack.d.ts
+/** Formal semantic identity — Stack root (Structure entity, layout rhythm). */
+declare const stackMeta: {
+  readonly displayName: "Stack";
+  readonly entity: "Structure";
+  readonly structure: "root";
+};
+/** Flow direction — vertical stacks, horizontal inlines. */
+type StackDirection = 'vertical' | 'horizontal';
+/** A step of the gap scale. */
+type StackGap = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+/** Cross-axis alignment. */
+type StackAlign = 'start' | 'center' | 'end' | 'stretch';
+/** Main-axis distribution. */
+type StackJustify = 'start' | 'center' | 'end' | 'between';
+/** Props for the Stack component. */
+interface StackProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'style' | 'className'> {
+  /**
+   * Flow direction. `vertical` stacks children in a column (reads the
+   * `gap.stack` scale); `horizontal` lays them in a row (reads `gap.inline`).
+   * @default 'vertical'
+   */
+  direction?: StackDirection;
+  /**
+   * Space between children, from the gap scale. There is no raw-length
+   * vocabulary — rhythm always comes from the scale.
+   * @default 'md'
+   */
+  gap?: StackGap;
+  /** Cross-axis alignment (`align-items`). @default 'stretch' */
+  align?: StackAlign;
+  /** Main-axis distribution (`justify-content`). @default 'start' */
+  justify?: StackJustify;
+  /** Allow children to wrap onto multiple lines. @default false */
+  wrap?: boolean;
+  /** The items to lay out. */
+  children?: React.ReactNode;
+}
+/**
+ * The layout rhythm primitive — a flex container spaced from the FSL gap scale.
+ *
+ * Entity = Structure. Use it to stack sections (`direction="vertical"`) or lay
+ * out a row of controls (`direction="horizontal"`) with consistent, themeable
+ * spacing. `gap`, `align`, and `justify` draw only from named scales/keywords —
+ * there is no raw `gap: 12px`, which is how spacing rhythm stays consistent
+ * across a product.
+ *
+ * @example
+ * ```tsx
+ * <Stack gap="lg">
+ *   <Heading level={2}>Payment</Heading>
+ *   <Stack direction="horizontal" gap="sm" justify="end">
+ *     <Button evaluation="muted">Cancel</Button>
+ *     <Button evaluation="primary">Save</Button>
+ *   </Stack>
+ * </Stack>
+ * ```
+ */
+declare const Stack: {
+  ({
+    direction,
+    gap,
+    align,
+    justify,
+    wrap,
+    children,
+    ...props
+  }: StackProps): import("react/jsx-runtime").JSX.Element;
+  displayName: "Stack";
+};
+//#endregion
+export { Stack, StackAlign, StackDirection, StackGap, StackJustify, StackProps, stackMeta };

package/dist/components/Stack/Stack.mjs

@@ -0,0 +1,88 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+import { vars } from "@ttoss/fsl-theme/vars";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/components/Stack/Stack.tsx
+/** Formal semantic identity — Stack root (Structure entity, layout rhythm). */
+var stackMeta = {
+  displayName: "Stack",
+  entity: "Structure",
+  structure: "root"
+};
+var GAP_STACK = {
+  xs: vars.spacing.gap.stack.xs,
+  sm: vars.spacing.gap.stack.sm,
+  md: vars.spacing.gap.stack.md,
+  lg: vars.spacing.gap.stack.lg,
+  xl: vars.spacing.gap.stack.xl
+};
+var GAP_INLINE = {
+  xs: vars.spacing.gap.inline.xs,
+  sm: vars.spacing.gap.inline.sm,
+  md: vars.spacing.gap.inline.md,
+  lg: vars.spacing.gap.inline.lg,
+  xl: vars.spacing.gap.inline.xl
+};
+var ALIGN = {
+  start: "flex-start",
+  center: "center",
+  end: "flex-end",
+  stretch: "stretch"
+};
+var JUSTIFY = {
+  start: "flex-start",
+  center: "center",
+  end: "flex-end",
+  between: "space-between"
+};
+/**
+* The layout rhythm primitive — a flex container spaced from the FSL gap scale.
+*
+* Entity = Structure. Use it to stack sections (`direction="vertical"`) or lay
+* out a row of controls (`direction="horizontal"`) with consistent, themeable
+* spacing. `gap`, `align`, and `justify` draw only from named scales/keywords —
+* there is no raw `gap: 12px`, which is how spacing rhythm stays consistent
+* across a product.
+*
+* @example
+* ```tsx
+* <Stack gap="lg">
+*   <Heading level={2}>Payment</Heading>
+*   <Stack direction="horizontal" gap="sm" justify="end">
+*     <Button evaluation="muted">Cancel</Button>
+*     <Button evaluation="primary">Save</Button>
+*   </Stack>
+* </Stack>
+* ```
+*/
+var Stack = ({
+  direction = "vertical",
+  gap = "md",
+  align = "stretch",
+  justify = "start",
+  wrap = false,
+  children,
+  ...props
+}) => {
+  const isHorizontal = direction === "horizontal";
+  return /* @__PURE__ */jsx("div", {
+    ...props,
+    "data-scope": "stack",
+    "data-part": "root",
+    "data-direction": direction,
+    "data-gap": gap,
+    style: {
+      display: "flex",
+      flexDirection: isHorizontal ? "row" : "column",
+      gap: isHorizontal ? GAP_INLINE[gap] : GAP_STACK[gap],
+      alignItems: ALIGN[align],
+      justifyContent: JUSTIFY[justify],
+      flexWrap: wrap ? "wrap" : "nowrap"
+    },
+    children
+  });
+};
+Stack.displayName = stackMeta.displayName;
+
+//#endregion
+export { Stack, stackMeta };

package/dist/components/Surface/Surface.cjs

@@ -0,0 +1,84 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+let _ttoss_fsl_theme_vars = require("@ttoss/fsl-theme/vars");
+let react_jsx_runtime = require("react/jsx-runtime");
+
+//#region src/components/Surface/Surface.tsx
+/** Formal semantic identity — Surface root (Structure entity, depth container). */
+var surfaceMeta = {
+  displayName: "Surface",
+  entity: "Structure",
+  structure: "root"
+};
+/** Inset padding per scale step; `none` collapses to zero. */
+var PADDING_BY_KEY = {
+  none: "0",
+  sm: _ttoss_fsl_theme_vars.vars.spacing.inset.surface.sm,
+  md: _ttoss_fsl_theme_vars.vars.spacing.inset.surface.md,
+  lg: _ttoss_fsl_theme_vars.vars.spacing.inset.surface.lg
+};
+/** Text colour for content sitting on the surface. */
+var SURFACE_TEXT = _ttoss_fsl_theme_vars.vars.colors.informational.primary.text?.default;
+/**
+* The surface's background colour. Raised strata read the tonal surface colour
+* (the "colour at depth"); `flat` — or a theme that ships no tonal group — is
+* canvas, so it falls back to the primary informational background.
+*/
+var backgroundFor = level => {
+  const tonal = _ttoss_fsl_theme_vars.vars.elevation.tonal;
+  if (level === "flat" || tonal === void 0) return _ttoss_fsl_theme_vars.vars.colors.informational.primary.background?.default;
+  return tonal[level];
+};
+/** The hairline boundary colour for the given evaluation. */
+var borderColorFor = evaluation => {
+  return _ttoss_fsl_theme_vars.vars.colors.informational[evaluation]?.border?.default ?? "transparent";
+};
+/**
+* A depth-bearing container — the surface primitive of the FSL grammar.
+*
+* Entity = Structure. Use it wherever a region needs to read as a distinct
+* surface: cards, panels, sheets, the body of a dialog. Pick the `level` by
+* how the surface should sit relative to the page, not by how it should look —
+* the theme decides the shadow and tonal treatment per mode. Non-interactive:
+* it owns no hover/focus chrome; interactivity belongs to the controls placed
+* inside it.
+*
+* @example
+* ```tsx
+* <Surface level="raised" padding="lg">
+*   <Heading level={3}>Storage</Heading>
+*   <Meter aria-label="Used" label="Used" value={72} />
+* </Surface>
+* ```
+*/
+var Surface = ({
+  level = "raised",
+  padding = "md",
+  evaluation = "muted",
+  children,
+  ...props
+}) => {
+  return /* @__PURE__ */(0, react_jsx_runtime.jsx)("div", {
+    ...props,
+    "data-scope": "surface",
+    "data-part": "root",
+    "data-level": level,
+    "data-evaluation": evaluation,
+    style: {
+      boxSizing: "border-box",
+      padding: PADDING_BY_KEY[padding],
+      color: SURFACE_TEXT,
+      background: backgroundFor(level),
+      boxShadow: _ttoss_fsl_theme_vars.vars.elevation.surface[level],
+      borderRadius: _ttoss_fsl_theme_vars.vars.radii.surface,
+      borderWidth: _ttoss_fsl_theme_vars.vars.border.outline.surface.width,
+      borderStyle: _ttoss_fsl_theme_vars.vars.border.outline.surface.style,
+      borderColor: borderColorFor(evaluation)
+    },
+    children
+  });
+};
+Surface.displayName = surfaceMeta.displayName;
+
+//#endregion
+exports.Surface = Surface;
+exports.surfaceMeta = surfaceMeta;

package/dist/components/Surface/Surface.d.cts

@@ -0,0 +1,72 @@
+
+import { EvaluationsFor } from "../../semantics/taxonomy.cjs";
+import * as React from "react";
+
+//#region src/components/Surface/Surface.d.ts
+/** Formal semantic identity — Surface root (Structure entity, depth container). */
+declare const surfaceMeta: {
+  readonly displayName: "Surface";
+  readonly entity: "Structure";
+  readonly structure: "root";
+};
+/** The elevation strata a Surface can express (elevation.md surface contract). */
+type SurfaceLevel = 'flat' | 'raised' | 'overlay' | 'blocking';
+/** Inner padding drawn from the surface inset scale. */
+type SurfacePadding = 'none' | 'sm' | 'md' | 'lg';
+/** Props for the Surface component. */
+interface SurfaceProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'style' | 'className'> {
+  /**
+   * Elevation stratum. `flat` sits flush with the page (no shadow); `raised`
+   * is the default card/panel depth; `overlay` floats above raised content;
+   * `blocking` is the strongest in-flow depth (dialog bodies). Depth is
+   * carried by the paired shadow recipe *and* the tonal surface colour, so it
+   * reads correctly in both light and dark (dark depth is the tonal step —
+   * shadows go invisible on a near-black canvas).
+   * @default 'raised'
+   */
+  level?: SurfaceLevel;
+  /**
+   * Inner padding from the surface inset scale. `none` removes padding for
+   * surfaces that host their own edge-to-edge content (lists, media).
+   * @default 'md'
+   */
+  padding?: SurfacePadding;
+  /**
+   * Emphasis of the hairline boundary. `muted` is the quiet default that lets
+   * elevation carry the separation; `primary` draws a firmer edge.
+   * @default 'muted'
+   */
+  evaluation?: EvaluationsFor<(typeof surfaceMeta)['entity']>;
+  /** The surface's content. */
+  children?: React.ReactNode;
+}
+/**
+ * A depth-bearing container — the surface primitive of the FSL grammar.
+ *
+ * Entity = Structure. Use it wherever a region needs to read as a distinct
+ * surface: cards, panels, sheets, the body of a dialog. Pick the `level` by
+ * how the surface should sit relative to the page, not by how it should look —
+ * the theme decides the shadow and tonal treatment per mode. Non-interactive:
+ * it owns no hover/focus chrome; interactivity belongs to the controls placed
+ * inside it.
+ *
+ * @example
+ * ```tsx
+ * <Surface level="raised" padding="lg">
+ *   <Heading level={3}>Storage</Heading>
+ *   <Meter aria-label="Used" label="Used" value={72} />
+ * </Surface>
+ * ```
+ */
+declare const Surface: {
+  ({
+    level,
+    padding,
+    evaluation,
+    children,
+    ...props
+  }: SurfaceProps): import("react/jsx-runtime").JSX.Element;
+  displayName: "Surface";
+};
+//#endregion
+export { Surface, SurfaceLevel, SurfacePadding, SurfaceProps, surfaceMeta };