@phis/ui 0.1.0 → 0.2.1

package/styles/layout-authoring-scaffold.css

@@ -51,6 +51,7 @@
 
   --phi-debug-layer-slot-background: transparent;
   --phi-debug-layer-slot-background-strong: transparent;
+  --phi-debug-layer-slot-background-soft: transparent;
   --phi-debug-layer-slot-border: transparent;
   --phi-debug-layer-slot-border-strong: transparent;
 
@@ -74,6 +75,8 @@
 
   --phi-debug-layer-slot-background: var(--ant-color-warning-bg);
   --phi-debug-layer-slot-background-strong: var(--ant-color-warning-bg-hover);
+  /* The Grid's track guides: a tint light enough that a slot's own band stays the stronger mark. */
+  --phi-debug-layer-slot-background-soft: color-mix(in srgb, var(--ant-color-warning-bg) 50%, transparent);
   --phi-debug-layer-slot-border: var(--ant-color-warning);
   --phi-debug-layer-slot-border-strong: var(--ant-color-warning-text);
 
@@ -97,6 +100,7 @@
 
   --phi-debug-layer-slot-background: transparent;
   --phi-debug-layer-slot-background-strong: transparent;
+  --phi-debug-layer-slot-background-soft: transparent;
   --phi-debug-layer-slot-border: transparent;
   --phi-debug-layer-slot-border-strong: transparent;
 
@@ -163,6 +167,7 @@
   --phi-debug-layer-layout-border: var(--ant-color-success-border-hover);
   --phi-debug-layer-slot-background: transparent;
   --phi-debug-layer-slot-background-strong: transparent;
+  --phi-debug-layer-slot-background-soft: transparent;
   --phi-debug-layer-slot-border: var(--ant-color-warning-border-hover);
   outline-width: 1px;
   outline-offset: -1px;
@@ -254,6 +259,20 @@
   justify-content: var(--phi-edit-scaffold-body-justify);
 }
 
+/*
+ * The drawer stands in for the slot child frame, so it owes the Layout what a frame would give it.
+ *
+ * A Structure Region's root Layout is rendered here rather than in a slot: there is no
+ * `.phi-slot-child` above it and therefore none of the fill rules in `layout.css`. The Layout box
+ * states only what the block configured (`resolvePhiLayoutBoxStyle`), so without this rule a Grid or
+ * Masonry root would be laid out at its content size in the Builder and at full size everywhere else.
+ */
+:where(.phi-edit-scaffold-drawer__body > .phi-layout) {
+  flex: 1 1 auto;
+  width: 100%;
+  height: 100%;
+}
+
 /* Its width is set inline where the bar is built, out of reach of the fill rule in `layout.css`. */
 :where(.phi-layout-scaffold-delete) {
   position: absolute;
@@ -504,6 +523,23 @@
   background: transparent;
 }
 
+/*
+ * And nothing at all while the Widget is being written in.
+ *
+ * Last of the state rules on purpose: they are all specificity zero, so document order decides, and this
+ * one has to outrank the hover a typing hand is inevitably producing. The band and the chrome are not
+ * drawn in that mode either (`render-root-node-scaffold.tsx`) -- what is left here is the outline, which
+ * hovering paints from the stylesheet and no prop can take back.
+ */
+:where(
+  .phi-builder-widget-scaffold:has(> .phi-builder-widget-scaffold__content--authoring)
+    > .phi-builder-widget-scaffold__state
+) {
+  outline-color: transparent;
+  background: transparent;
+  box-shadow: inset 0 0 0 1px transparent;
+}
+
 .phi-builder-widget-scaffold[data-phi-slot-child-kind="widget"]::before {
   content: attr(data-phi-builder-widget-title);
   position: absolute;
@@ -554,20 +590,31 @@
   pointer-events: auto;
 }
 
+/*
+ * And no band at all while the Widget is being written in, for the same reason the outline goes.
+ *
+ * `content: none` rather than an empty string: the band is `attr(data-phi-builder-widget-title)`, and a
+ * scaffold that withholds that attribute still draws the chip the band is made of -- padding, border and
+ * background around nothing. Stated after the rules that show the band, since it weighs the same as the
+ * one that fills it.
+ */
+.phi-builder-widget-scaffold:has(> .phi-builder-widget-scaffold__content--authoring)::before {
+  content: none;
+}
+
 :where(.phi-builder-root-scaffold) {
   min-height: 0;
 }
 
+/*
+ * The slot itself is a slot child frame, so its width, height, minima and maxima are written inline by
+ * the frame from the root's geometry. Only what the frame does not write stands here -- and `align-self`
+ * is not on that list either: the frame states `auto` inline, deliberately, so the Layout's anchor
+ * rather than a stylesheet decides whether the root is stretched.
+ */
 :where(.phi-builder-root-scaffold__slot) {
   display: flex;
   flex-direction: column;
-  width: var(--phi-root-scaffold-width);
-  height: var(--phi-root-scaffold-height);
-  min-width: var(--phi-root-scaffold-min-width);
-  max-width: var(--phi-root-scaffold-max-width);
-  min-height: var(--phi-root-scaffold-min-height);
-  max-height: var(--phi-root-scaffold-max-height);
-  align-self: stretch;
   justify-content: flex-start;
 }
 

package/styles/layout.css

@@ -187,19 +187,19 @@
   min-height: 0;
 }
 
-:where(.phi-layout-scaffold-anchor__content[data-phi-slot-size-inline="fill"][data-phi-layout-explicit-width="true"]) {
-  width: 100%;
-}
-
-:where(.phi-layout-scaffold-anchor__content[data-phi-slot-size-block="fill"][data-phi-layout-explicit-height="true"]) {
-  height: 100%;
-}
-
-:where(.phi-layout-scaffold-anchor__content[data-phi-slot-size-inline="fill"]:not([data-phi-layout-explicit-width="true"])) {
+/*
+ * Filling is filling, whether or not a width was also stated.
+ *
+ * These were four rules -- with an explicit size and without, per axis -- carrying the same
+ * declaration, split for a distinction that was never drawn. The distinction is real and now lives
+ * where it belongs: a stated size makes the axis `fixed`, so "fill" here can no longer mean anything
+ * but fill.
+ */
+:where(.phi-layout-scaffold-anchor__content[data-phi-slot-size-inline="fill"]) {
   width: 100%;
 }
 
-:where(.phi-layout-scaffold-anchor__content[data-phi-slot-size-block="fill"]:not([data-phi-layout-explicit-height="true"])) {
+:where(.phi-layout-scaffold-anchor__content[data-phi-slot-size-block="fill"]) {
   height: 100%;
 }
 
@@ -279,10 +279,19 @@
   min-width: 0;
 }
 
+/*
+ * `padding-inline-start` rather than the grid's `column-gap`, and with a fallback of nothing.
+ *
+ * The gap between two columns of a row is not the gap between a label and its own control, and a
+ * `column-gap` cannot tell them apart -- it falls on every boundary between adjacent elements. So the
+ * Form Layout marks the one cell that opens a column and only that cell is moved. The fallback is for
+ * the cells that are not in a form's row at all, the actions row below it, which writes none of these.
+ */
 .phi-form-cell {
   grid-row: var(--phi-form-cell-row-compact);
   grid-column: var(--phi-form-cell-columns-compact);
   margin-block-end: var(--phi-form-cell-gap-compact);
+  padding-inline-start: var(--phi-form-cell-lead-compact, 0px);
   min-width: 0;
 }
 
@@ -297,18 +306,30 @@
   max-width: 100%;
 }
 
-/* The actions row opens its own grid, so it has no row of the form to sit in. */
+/*
+ * The actions row opens its own grid, so it has no row of the form to sit in, and it takes the tracks
+ * the Form Widget wrote for it: the layout's control range, which is where the inputs above it stand.
+ * Reading the label column instead would indent the button past a form whose labels sit on top of
+ * their controls, since that form has no label column to stand after.
+ */
 .phi-form-descriptor-actions > .phi-form-cell {
   grid-row: auto;
-  grid-column: 1 / 25;
+  grid-column: var(--phi-form-actions-columns-compact);
   margin-block-end: 0;
 }
 
-@container phi-form (min-width: 360px) {
+/*
+ * The same numbers as `PHI_FORM_RESPONSIVE_MIN_WIDTH`, off the container-breakpoint scale in
+ * `theme/phi-container-breakpoints.ts`. A container query cannot read a custom property for its
+ * threshold, so the literal stands here and the contract states it in TypeScript; if one side moves,
+ * the other has to move with it.
+ */
+@container phi-form (min-width: 377px) {
   .phi-form-cell {
     grid-row: var(--phi-form-cell-row-medium);
     grid-column: var(--phi-form-cell-columns-medium);
     margin-block-end: var(--phi-form-cell-gap-medium);
+    padding-inline-start: var(--phi-form-cell-lead-medium, 0px);
   }
 
   .phi-form-cell--label {
@@ -317,21 +338,70 @@
   }
 
   .phi-form-descriptor-actions > .phi-form-cell {
-    grid-row: auto;
-    grid-column: var(--phi-form-label-end, 7) / 25;
-    margin-block-end: 0;
+    grid-column: var(--phi-form-actions-columns-medium);
   }
 }
 
-@container phi-form (min-width: 768px) {
+@container phi-form (min-width: 610px) {
   .phi-form-cell {
     grid-row: var(--phi-form-cell-row-wide);
     grid-column: var(--phi-form-cell-columns-wide);
     margin-block-end: var(--phi-form-cell-gap-wide);
+    padding-inline-start: var(--phi-form-cell-lead-wide, 0px);
   }
 
   .phi-form-cell--label {
     min-height: var(--phi-form-label-height-wide);
     padding-inline-end: var(--phi-form-label-pad-wide);
   }
+
+  .phi-form-descriptor-actions > .phi-form-cell {
+    grid-column: var(--phi-form-actions-columns-wide);
+  }
+}
+
+/*
+ * The Grid's slots (LAYOUTING.md, "Grid slot placement").
+ *
+ * Each slot writes where it stands at all three widths as custom properties
+ * (`resolvePhiGridSlotColumnProperties`), and these rules pick one by the Grid's own width, the way the
+ * form grid above does -- so the markup the server sends already stands where it stays. The Grid's
+ * Layout box is the `phi-grid` container and is measured inside its padding, as a form is.
+ *
+ * The column gap is padding, not `column-gap`: a `column-gap` falls between all 24 tracks, so a 16px
+ * gap made 368px the narrowest a Grid could be. Each slot insets its content by its share of the gaps,
+ * `lead` 24ths of one before it and `trail` 24ths after, which puts its edges where a `column-gap` did
+ * while there is room and narrows the slots when there is not. Every slot writes all nine properties;
+ * the fallbacks only keep a declaration valid should one be missing, rather than dropping the column.
+ */
+.phi-grid-layout__slot {
+  grid-column: var(--phi-grid-slot-columns-compact, auto);
+  padding-inline-start:
+    calc(var(--phi-grid-column-gap, 0px) * var(--phi-grid-slot-lead-compact, 0) / 24);
+  padding-inline-end:
+    calc(var(--phi-grid-column-gap, 0px) * var(--phi-grid-slot-trail-compact, 0) / 24);
+}
+
+/*
+ * The same numbers as `PHI_GRID_RESPONSIVE_MIN_WIDTH` (components/layouts/phi-grid-contract.ts), held
+ * together by `validate-container-breakpoint-contracts.ts` for the reason the form's are.
+ */
+@container phi-grid (min-width: 377px) {
+  .phi-grid-layout__slot {
+    grid-column: var(--phi-grid-slot-columns-medium, auto);
+    padding-inline-start:
+      calc(var(--phi-grid-column-gap, 0px) * var(--phi-grid-slot-lead-medium, 0) / 24);
+    padding-inline-end:
+      calc(var(--phi-grid-column-gap, 0px) * var(--phi-grid-slot-trail-medium, 0) / 24);
+  }
+}
+
+@container phi-grid (min-width: 610px) {
+  .phi-grid-layout__slot {
+    grid-column: var(--phi-grid-slot-columns-wide, auto);
+    padding-inline-start:
+      calc(var(--phi-grid-column-gap, 0px) * var(--phi-grid-slot-lead-wide, 0) / 24);
+    padding-inline-end:
+      calc(var(--phi-grid-column-gap, 0px) * var(--phi-grid-slot-trail-wide, 0) / 24);
+  }
 }

package/styles/root.css

@@ -14,8 +14,9 @@ body {
 }
 
 /* The ground is painted by the Theme Root Background layer (data-phi-root-background), fixed
-   behind the content; .ant-app stays transparent so that layer shows through. */
-[data-phi-root-layout="true"] > .ant-app {
+   behind the content; the ground stays transparent so that layer shows through. It used to be Ant
+   Design's `.ant-app` element, which only ever happened to sit here. */
+[data-phi-root-layout="true"] > [data-phi-app-ground="true"] {
   min-height: inherit;
   background: transparent;
   color: var(--ant-color-text);
@@ -126,6 +127,30 @@ samp {
   animation-play-state: running;
 }
 
+/*
+ * On ready, the whole rule inside the query that asks whether anything can release it.
+ *
+ * The animation is held at its first frame until the page has finished arriving, so a Widget whose
+ * content the server streams in a segment of its own can land, and everything below it can settle,
+ * behind an entrance that has not started. Only scripting sets the state that releases it; where there
+ * is none the Block would stand at that first frame for good, which for a fade in means invisible. So
+ * without scripting there is no animation at all and the Block is simply there.
+ */
+@media (scripting: enabled) {
+  :where([data-phi-renderable-block="true"][data-phi-effects-transition="composite"][data-phi-effects-trigger="on_ready"]) {
+    animation-composition: var(--phi-effects-animation-composition, replace);
+    animation-delay: var(--phi-effects-animation-delay, 0ms);
+    animation-duration: var(--phi-effects-animation-duration, 1000ms);
+    animation-name: var(--phi-effects-animation-name);
+    animation-play-state: paused;
+    animation-timing-function: var(--phi-effects-animation-easing, ease-out);
+  }
+
+  :where([data-phi-renderable-block="true"][data-phi-effects-transition="composite"][data-phi-effects-trigger="on_ready"][data-phi-effects-state="running"]) {
+    animation-play-state: running;
+  }
+}
+
 :where([data-phi-renderable-block="true"][data-phi-effects-transition="composite"][data-phi-effects-trigger="on_hover"]:hover),
 :where([data-phi-renderable-block="true"][data-phi-effects-transition="composite"][data-phi-effects-trigger="on_focus"]:focus-within) {
   animation-composition: var(--phi-effects-animation-composition, replace);

package/styles/shell.css

@@ -24,6 +24,16 @@
   container-type: inline-size;
 }
 
+/*
+ * A device band, not a content threshold, although it is written as a container query.
+ *
+ * `phi-render-viewport` is the window less the sider, so what these three measure is the screen. They
+ * are deliberately NOT on the container-breakpoint scale in `theme/phi-container-breakpoints.ts`: a
+ * Phi number has to fall where it fits content, and 377 sits between a 375px phone and a 390px one,
+ * which would put two phones of one class on opposite sides of a boundary. They also carry
+ * `viewportFlags`, so they decide whether a block exists on the page rather than how it is drawn --
+ * moving them adds and removes content.
+ */
 @container phi-render-viewport (width < 768px) {
   :where([data-phi-viewport-flags="2"], [data-phi-viewport-flags="4"], [data-phi-viewport-flags="6"]) {
     display: none !important;

package/theme/antd-css-var-contract.d.ts

@@ -28,6 +28,8 @@ export declare const PHI_COLOR: {
     readonly linkActive: "var(--ant-color-link-active)";
     readonly split: "var(--ant-color-split)";
     readonly error: "var(--ant-color-error)";
+    readonly success: "var(--ant-color-success)";
+    readonly warning: "var(--ant-color-warning)";
 };
 export declare const PHI_SPACE: {
     readonly xxs: "var(--ant-padding-xxs)";
@@ -69,9 +71,6 @@ export declare const PHI_SHADOW: {
     readonly secondary: "var(--ant-box-shadow-secondary)";
     readonly tertiary: "var(--ant-box-shadow-tertiary)";
 };
-export declare const PHI_MOTION: {
-    readonly durationMid: "var(--ant-motion-duration-mid)";
-};
 export declare const PHI_FONT_SIZE: {
     readonly base: "var(--ant-font-size)";
     readonly sm: "var(--ant-font-size-sm)";

package/theme/antd-css-var-contract.js

@@ -28,6 +28,8 @@ export const PHI_COLOR = {
     linkActive: "var(--ant-color-link-active)",
     split: "var(--ant-color-split)",
     error: "var(--ant-color-error)",
+    success: "var(--ant-color-success)",
+    warning: "var(--ant-color-warning)",
 };
 export const PHI_SPACE = {
     xxs: "var(--ant-padding-xxs)",
@@ -69,9 +71,6 @@ export const PHI_SHADOW = {
     secondary: "var(--ant-box-shadow-secondary)",
     tertiary: "var(--ant-box-shadow-tertiary)",
 };
-export const PHI_MOTION = {
-    durationMid: "var(--ant-motion-duration-mid)",
-};
 export const PHI_FONT_SIZE = {
     base: "var(--ant-font-size)",
     sm: "var(--ant-font-size-sm)",

package/theme/phi-container-breakpoints.d.ts

@@ -1,2 +1,35 @@
-export declare const PHI_CONTAINER_BREAKPOINT_COL2 = 144;
-export declare const PHI_CONTAINER_BREAKPOINT_COL3 = 377;
+/**
+ * The widths a block may switch its own layout at.
+ *
+ * These are *content* thresholds: they answer "at what width does this stop fitting", and they are
+ * measured on the block's own box -- by a container query or a `ResizeObserver` -- not on the window.
+ * A form standing in a 480px dialog on a desk monitor is a narrow form, whatever the screen says.
+ *
+ * They are the house sequence, because a threshold on this scale is a threshold somebody chose. What
+ * stood here before was three different answers: Ant Design's device numbers read as content
+ * thresholds by the Grid, a hand-written pair in the Form's stylesheet, and this file with two.
+ *
+ * **They are not device bands.** 377 sits between a 375px phone and a 390px one, and 610 sits inside
+ * the tablet range, so a threshold meant to tell a phone from a tablet has no number here and must not
+ * be given one. The Shell's 768 and 1200 are that kind: they are written as container queries because
+ * the Shell measures the render viewport, but what they mean is the device, and they carry
+ * `viewportFlags` -- which decide whether a block exists at all, not how it is drawn. They stay where
+ * they are, and `styles/shell.css` says so in place.
+ *
+ * Which pair a block picks is the block's own business, the way a component picks a spacing step. A
+ * form's two columns stop fitting far earlier than a 24-track Grid's do, so they switch at different
+ * widths off the same ruler.
+ */
+export declare const PHI_CONTAINER_BREAKPOINTS: readonly [144, 233, 377, 610, 987];
+export type PhiContainerBreakpoint = (typeof PHI_CONTAINER_BREAKPOINTS)[number];
+/** Two columns of anything need this much before one column stops being the better answer. */
+export declare const PHI_CONTAINER_BREAKPOINT_COL2: PhiContainerBreakpoint;
+/** Three columns, and the width at which a label fits beside a control rather than over it. */
+export declare const PHI_CONTAINER_BREAKPOINT_COL3: PhiContainerBreakpoint;
+/**
+ * As wide as the house lets content get (`PHI_LAYOUT.contentMax`), so a block this wide is standing in
+ * a full-width Region rather than in a content column.
+ */
+export declare const PHI_CONTAINER_BREAKPOINT_CONTENT: PhiContainerBreakpoint;
+/** The wide content maximum (`PHI_LAYOUT.contentMaxWide`): a Region running the width of the page. */
+export declare const PHI_CONTAINER_BREAKPOINT_REGION: PhiContainerBreakpoint;

package/theme/phi-container-breakpoints.js

@@ -1,2 +1,34 @@
+/**
+ * The widths a block may switch its own layout at.
+ *
+ * These are *content* thresholds: they answer "at what width does this stop fitting", and they are
+ * measured on the block's own box -- by a container query or a `ResizeObserver` -- not on the window.
+ * A form standing in a 480px dialog on a desk monitor is a narrow form, whatever the screen says.
+ *
+ * They are the house sequence, because a threshold on this scale is a threshold somebody chose. What
+ * stood here before was three different answers: Ant Design's device numbers read as content
+ * thresholds by the Grid, a hand-written pair in the Form's stylesheet, and this file with two.
+ *
+ * **They are not device bands.** 377 sits between a 375px phone and a 390px one, and 610 sits inside
+ * the tablet range, so a threshold meant to tell a phone from a tablet has no number here and must not
+ * be given one. The Shell's 768 and 1200 are that kind: they are written as container queries because
+ * the Shell measures the render viewport, but what they mean is the device, and they carry
+ * `viewportFlags` -- which decide whether a block exists at all, not how it is drawn. They stay where
+ * they are, and `styles/shell.css` says so in place.
+ *
+ * Which pair a block picks is the block's own business, the way a component picks a spacing step. A
+ * form's two columns stop fitting far earlier than a 24-track Grid's do, so they switch at different
+ * widths off the same ruler.
+ */
+export const PHI_CONTAINER_BREAKPOINTS = [144, 233, 377, 610, 987];
+/** Two columns of anything need this much before one column stops being the better answer. */
 export const PHI_CONTAINER_BREAKPOINT_COL2 = 144;
+/** Three columns, and the width at which a label fits beside a control rather than over it. */
 export const PHI_CONTAINER_BREAKPOINT_COL3 = 377;
+/**
+ * As wide as the house lets content get (`PHI_LAYOUT.contentMax`), so a block this wide is standing in
+ * a full-width Region rather than in a content column.
+ */
+export const PHI_CONTAINER_BREAKPOINT_CONTENT = 610;
+/** The wide content maximum (`PHI_LAYOUT.contentMaxWide`): a Region running the width of the page. */
+export const PHI_CONTAINER_BREAKPOINT_REGION = 987;

package/theme/phi-control-shape.d.ts

@@ -31,8 +31,8 @@ export declare function resolvePhiUniformControlShape(corners: PhiControlShapeCo
 /** The shape a resolved Theme renders; the runtime fold has already put the style block's under it. */
 export declare function resolvePhiControlShape(value: unknown): PhiControlShape;
 /**
- * Radius scale a Control shape resolves to. `SITE-CONFIG.md` requires the adapter to resolve the
- * preset "for the active `controlSize`", so a shape is a scale rather than a single number.
+ * Radius scale a Control shape resolves to. A shape applies at every Control size (THEME.md, "Control
+ * shape"), so it is a scale rather than a single number.
  *
  * - `square` and `pill` are ABSOLUTE statements about geometry. No size can make "no rounding" or
  *   "capsule" partially true, so both flatten every step: a small pill Button that is not a pill is
@@ -45,6 +45,10 @@ export declare function resolvePhiControlShape(value: unknown): PhiControlShape;
  * `inner*` is the radius of a box nested INSIDE a Control body -- the Segmented item and thumb. antd
  * keeps it one step below the body so the item never overruns its container; an absolute shape has to
  * reach it too, or a pill Segmented ends up with square items inside a capsule.
+ *
+ * `grown*` is the radius of a Control whose height is NOT one Control line: a Textarea, a Select holding
+ * enough tags to wrap, a Mentions box. Only `pill` differs there, and it has to -- see
+ * `resolvePhiGrownControlShapeRadii`.
  */
 export type PhiControlShapeRadii = {
     sm: number;
@@ -53,12 +57,18 @@ export type PhiControlShapeRadii = {
     innerSm: number;
     innerMd: number;
     innerLg: number;
+    grownSm: number;
+    grownMd: number;
+    grownLg: number;
 };
 export type PhiControlShapeRadiusTokens = {
     borderRadiusXS?: unknown;
     borderRadiusSM?: unknown;
     borderRadius?: unknown;
     borderRadiusLG?: unknown;
+    controlHeightSM?: unknown;
+    controlHeight?: unknown;
+    controlHeightLG?: unknown;
 };
 export declare function resolvePhiControlShapeRadii(shape: PhiControlShape, tokens?: PhiControlShapeRadiusTokens): PhiControlShapeRadii;
 export declare function resolvePhiControlShapeRadius(shape: PhiControlShape, tokens: PhiControlShapeRadiusTokens): number;
@@ -73,6 +83,11 @@ export declare function resolvePhiControlShapeRadius(shape: PhiControlShape, tok
  * The default size is deliberately absent: it is already carried by the component tokens, and a CSS
  * rule strong enough to set it would also have to outrank antd's own `-circle` and `-round` Button
  * shapes, which stay authoritative.
+ *
+ * `grownMd` is the one exception, and for the reason that does not apply: the default size is exactly
+ * where the component token is wrong for a grown Control, so something has to say otherwise, and no
+ * Button ever grows -- the selectors that read it name a Textarea, a multiple Select and a Mentions box,
+ * and reach no Button shape at all.
  */
 export type PhiControlShapeCssVarSlot = Exclude<keyof PhiControlShapeRadii, "md">;
 export declare const PHI_CONTROL_SHAPE_CSS_VARS: {
@@ -81,13 +96,48 @@ export declare const PHI_CONTROL_SHAPE_CSS_VARS: {
     readonly innerSm: "--phi-control-radius-inner-sm";
     readonly innerMd: "--phi-control-radius-inner-md";
     readonly innerLg: "--phi-control-radius-inner-lg";
+    readonly grownSm: "--phi-control-radius-grown-sm";
+    readonly grownMd: "--phi-control-radius-grown-md";
+    readonly grownLg: "--phi-control-radius-grown-lg";
 };
 export declare function buildPhiControlShapeCssVars(shape: PhiControlShape, tokens?: PhiControlShapeRadiusTokens): Record<`--${string}`, string>;
+/**
+ * A surface's own corner, chosen by the same setting and answered on the surface scale.
+ *
+ * A surface keeps a surface's radii -- `pill` on a Table or a Layout would be a capsule around a grid
+ * or around a column of content, which is not a thing. What the shape says about them is softer: how
+ * far this Site rounds, as one step on the scale it already has. `square` takes none, and the other
+ * three take the three radius tokens in order, so the number a surface wears is always one somebody
+ * could have written into the numeric scale by hand.
+ *
+ * Its readers are every surface that draws a box: a Table (`headerBorderRadius`, and the clip in its CSS
+ * Module), a Collapse (`collapsePanelBorderRadius`, its panels), a Tree (its node grounds through the
+ * component token, its frame through the variable), a Layout (its box, wherever the author configured no
+ * radius of their own), and the eight components whose box is the global `borderRadiusLG` -- a Card, a Modal, and the six panels that open over the page. An
+ * explicit radius always wins -- this is the answer to "nothing was said", not a ceiling.
+ */
+export declare const PHI_SURFACE_SHAPE_CSS_VAR = "--phi-surface-radius";
+export declare function resolvePhiSurfaceShapeRadius(shape: PhiControlShape, tokens?: PhiControlShapeRadiusTokens): number;
+/**
+ * The Tooltip's corner, which is the surface step everywhere but `pill`.
+ *
+ * `pill` cannot use the abbreviation here. Ant Design computes the Tooltip's MINIMUM WIDTH from this
+ * number -- `tooltipBorderRadius * 2 + sizePopupArrow`, and again with the arrow offset for the edge
+ * placements -- so `PHI_CONTROL_SHAPE_FULL_RADIUS` would ask for a tooltip twenty thousand pixels wide,
+ * and `min-width` beats the `maxWidth: 250` that would otherwise have caught it. The abbreviation works
+ * where the number is only ever read as a radius and clamped by the browser; here it is arithmetic.
+ *
+ * So the capsule is stated rather than abbreviated, the same way a grown Control states it: half the
+ * Control height, which is exactly a Tooltip's own capsule because `minHeight` IS the Control height. A
+ * Tooltip that wraps to a second line then holds that corner instead of growing an arc across its side.
+ */
+export declare function resolvePhiTooltipShapeRadius(shape: PhiControlShape, tokens?: PhiControlShapeRadiusTokens): number;
+export declare function applyPhiSurfaceShapeComponentTokens(components: Record<string, Record<string, unknown>>, shape: PhiControlShape, tokens: PhiControlShapeRadiusTokens): Record<string, Record<string, unknown>>;
 /**
  * Applies the shape to the Control components, outranking a raw adapter-level radius override.
  *
- * `SITE-CONFIG.md` requires this direction: "the resolved semantic Control shape takes precedence over
- * conflicting raw adapter-level component-radius overrides so there is one effective source of truth."
+ * THEME.md, "Control shape", requires this direction: for Phi Controls the shape wins over conflicting
+ * component radius overrides, so there is one effective source of truth.
  * Overriding a single corner is a different layer and never conflicts -- antd carries only scalar radius
  * tokens, so a Widget config such as `borderTopLeftRadius` owns that case.
  *