@godxjp/ui 18.12.15 → 18.12.17

package/dist/components/data-display/descriptions.d.ts

@@ -5,10 +5,19 @@ export interface DescriptionsProps {
     columns?: 1 | 2 | 3;
     /** Label placement within each item. Default `vertical` (label over value). */
     layout?: DescriptionsLayoutProp;
+    /**
+     * Text alignment of each item's label within its label column — the SAME contract `Form`
+     * exposes (gh#294), so a `Descriptions` composed beside a `Form`/`FormField` (a read-only
+     * name/email block above an editable role field, for example) can be told to match it. Applies
+     * only in `layout="horizontal"` — a vertical label sits above the value and end-aligning it
+     * there would read as a mistake, exactly like `Form`'s own contract. Default `"start"`, matching
+     * this component's historical unconditional left-align — no existing consumer's render changes.
+     */
+    labelAlign?: "start" | "end";
     className?: string;
     children: React.ReactNode;
 }
-export declare function Descriptions({ columns, layout, className, children, }: DescriptionsProps): React.JSX.Element;
+export declare function Descriptions({ columns, layout, labelAlign, className, children, }: DescriptionsProps): React.JSX.Element;
 export declare namespace Descriptions {
     var Item: ({ label, mono, span, className, children, }: DescriptionsItemProps) => React.JSX.Element;
 }

package/dist/components/data-display/descriptions.js

@@ -2,15 +2,20 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { cn } from "../../lib/utils.js";
-const DescriptionsLayoutContext = React.createContext("vertical");
+const DescriptionsLayoutContext = React.createContext({
+  layout: "vertical",
+  labelAlign: "start"
+});
 function Descriptions({
   columns = 2,
   layout = "vertical",
+  labelAlign = "start",
   className,
   children
 }) {
   const colsClass = columns === 1 ? "grid-cols-1" : columns === 3 ? "grid-cols-1 sm:grid-cols-2 lg:grid-cols-3" : "grid-cols-1 sm:grid-cols-2";
-  return /* @__PURE__ */ jsx(DescriptionsLayoutContext.Provider, { value: layout, children: /* @__PURE__ */ jsx("dl", { className: cn("grid gap-x-6 gap-y-3", colsClass, className), children }) });
+  const context = React.useMemo(() => ({ layout, labelAlign }), [layout, labelAlign]);
+  return /* @__PURE__ */ jsx(DescriptionsLayoutContext.Provider, { value: context, children: /* @__PURE__ */ jsx("dl", { className: cn("grid gap-x-6 gap-y-[var(--descriptions-row-gap)]", colsClass, className), children }) });
 }
 Descriptions.Item = function DescriptionsItem({
   label,
@@ -19,7 +24,7 @@ Descriptions.Item = function DescriptionsItem({
   className,
   children
 }) {
-  const layout = React.useContext(DescriptionsLayoutContext);
+  const { layout, labelAlign } = React.useContext(DescriptionsLayoutContext);
   const spanClass = span === 2 ? "sm:col-span-2" : span === 3 ? "sm:col-span-2 lg:col-span-3" : "";
   return /* @__PURE__ */ jsxs(
     "div",
@@ -38,7 +43,18 @@ Descriptions.Item = function DescriptionsItem({
         className
       ),
       children: [
-        /* @__PURE__ */ jsx("dt", { className: "text-muted-foreground text-xs", children: label }),
+        /* @__PURE__ */ jsx(
+          "dt",
+          {
+            className: cn(
+              "text-muted-foreground text-xs",
+              // `end`-align only ever applies in horizontal layout — same guard `Form` uses, so a
+              // vertical label (already above its value) never mistakenly right-aligns (gh#294).
+              layout === "horizontal" && labelAlign === "end" && "text-end"
+            ),
+            children: label
+          }
+        ),
         /* @__PURE__ */ jsx("dd", { className: cn("text-sm break-all", mono && "font-mono"), children })
       ]
     }

package/dist/components/data-entry/form-field.d.ts

@@ -1,4 +1,4 @@
 import * as React from "react";
 import type { FormFieldProp } from "../../props/components/data-entry.prop.js";
 export type { FormFieldProp, FormFieldProp as FormFieldProps, } from "../../props/components/data-entry.prop.js";
-export declare function FormField({ id, label, required, helper, error, labelAddon, layout: layoutProp, labelWidth: labelWidthProp, controlWidth: controlWidthProp, colSpan, className, children, }: FormFieldProp): React.JSX.Element;
+export declare function FormField({ id, label, required, helper, error, labelAddon, layout: layoutProp, labelWidth: labelWidthProp, controlWidth: controlWidthProp, colSpan, className, children, staticText, }: FormFieldProp): React.JSX.Element;

package/dist/components/data-entry/form-field.js

@@ -19,7 +19,8 @@ function FormField({
   controlWidth: controlWidthProp,
   colSpan,
   className,
-  children
+  children,
+  staticText
 }) {
   const form = useFormLayout();
   const layout = layoutProp ?? form?.layout ?? "vertical";
@@ -32,14 +33,19 @@ function FormField({
   const labelId = `${resolvedId}-label`;
   const helperId = helper ? `${resolvedId}-helper` : void 0;
   const errorId = error ? `${resolvedId}-error` : void 0;
-  if (typeof process !== "undefined" && process.env?.NODE_ENV !== "production" && !React.isValidElement(children)) {
+  const isStatic = staticText !== void 0;
+  if (!isStatic && typeof process !== "undefined" && process.env?.NODE_ENV !== "production" && !React.isValidElement(children)) {
     console.warn(
-      "FormField expects a single React element child to receive aria-describedby/aria-errormessage; the helper text and error message will not be associated with the control."
+      "FormField expects a single React element child to receive aria-describedby/aria-errormessage; the helper text and error message will not be associated with the control. Pass plain text via `staticText` instead of `children` for a read-only value row."
     );
   }
   const childProps = React.isValidElement(children) ? children.props : void 0;
   const mergeIds = mergeAriaIds;
-  const childWithA11y = React.isValidElement(children) ? React.cloneElement(children, {
+  const childWithA11y = isStatic ? (
+    // Byte-for-byte the same value typography as `Descriptions.Item`'s `dd` (gh#294), so a
+    // read-only FormField row and a Descriptions value are indistinguishable when mixed.
+    /* @__PURE__ */ jsx("span", { className: "text-sm break-all", children: staticText })
+  ) : React.isValidElement(children) ? React.cloneElement(children, {
     // The label is associated via aria-labelledby (not <label for>): composite
     // controls (Radio.Group, checkbox lists, range pairs) have no labelable root,
     // and a dangling `for` triggers Chrome's "Incorrect use of <label>" issue.
@@ -52,14 +58,8 @@ function FormField({
     "aria-label": childProps?.["aria-label"] ?? (typeof label === "string" ? label : void 0),
     // Helper and error can coexist: helper stays on aria-describedby, the error on
     // aria-errormessage (surfaced when aria-invalid is true).
-    "aria-describedby": mergeIds(
-      childProps?.["aria-describedby"],
-      helperId
-    ),
-    "aria-errormessage": mergeIds(
-      childProps?.["aria-errormessage"],
-      errorId
-    ),
+    "aria-describedby": mergeIds(childProps?.["aria-describedby"], helperId),
+    "aria-errormessage": mergeIds(childProps?.["aria-errormessage"], errorId),
     "aria-required": required ? true : childProps?.["aria-required"],
     "aria-invalid": error ? true : childProps?.["aria-invalid"]
   }) : children;

package/dist/props/components/data-entry.prop.d.ts

@@ -90,7 +90,17 @@ export type FormProp = React.FormHTMLAttributes<HTMLFormElement> & {
     density?: DensityProp;
     className?: ClassNameProp;
 };
-/** @see FormField */
+/**
+ * @see FormField — exactly one of `children` (an interactive control) or `staticText` (gh#294):
+ * a read-only VALUE row inside the same Form, styled to match `Descriptions.Item`'s value
+ * typography (`text-sm break-all`) byte-for-byte. This is the "mixed read-only + editable fields
+ * on one form" case (an immutable name/email row above an editable role Select, for example) —
+ * putting the read-only rows through FormField itself, not a separate `Descriptions` composed
+ * alongside it, gets perfect layout/labelAlign/row-gap sync FOR FREE because it IS the same
+ * component reading the same Form context, rather than two components whose contracts need
+ * reconciling. `staticText` skips FormField's control a11y wiring (id/aria-labelledby/
+ * aria-describedby cloning) entirely — there is no real control to label, so none of that applies.
+ */
 export type FormFieldProp = {
     /** Optional — auto-generated and injected into the child control when omitted. */
     id?: IdProp;
@@ -110,6 +120,28 @@ export type FormFieldProp = {
     colSpan?: number;
     className?: ClassNameProp;
     children: React.ReactNode;
+    staticText?: never;
+} | {
+    /** Optional — auto-generated and injected into the child control when omitted. */
+    id?: IdProp;
+    label: LabelProp;
+    required?: RequiredProp;
+    helper?: HelperProp;
+    error?: ErrorProp;
+    /** Optional control rendered inline after the label (e.g. a help button). */
+    labelAddon?: React.ReactNode;
+    /** Override the Form's layout for this field only. */
+    layout?: FormLayoutProp;
+    /** Override the Form's label width for this field (horizontal layout). */
+    labelWidth?: WidthProp;
+    /** Override the Form's control width for this field. */
+    controlWidth?: WidthProp;
+    /** Span N columns when inside a `columns` Form grid. */
+    colSpan?: number;
+    className?: ClassNameProp;
+    children?: never;
+    /** Read-only value — renders as `Descriptions.Item`-matched text instead of a control. */
+    staticText: React.ReactNode;
 };
 /** @see SearchInput */
 export type SearchInputProp = FieldA11yProps & {

package/dist/styles/form-layout.css

@@ -12,7 +12,25 @@
   .ui-form {
     display: flex;
     flex-direction: column;
-    gap: var(--space-4);
+  }
+
+  /* Row rhythm between a Form's own top-level blocks (gh#295) — e.g. the field group's
+   * CardContent and its CardFooter action row. MARGIN, not flex `gap`: `gap` only reaches DIRECT
+   * children, which is dead the moment a consumer needs a CardFooter Save button to actually
+   * submit (it must stay a `<form>` descendant, so Form has to wrap CardContent — the FormFields
+   * become grandchildren, past flex `gap`'s reach). Margin-based sibling spacing works at any
+   * depth as long as the elements are literal siblings. */
+  .ui-form > * + * {
+    margin-block-start: var(--form-block-gap);
+  }
+
+  /* Field-to-field row rhythm (gh#295) — MORE SPECIFIC than the rule above (two class selectors
+   * beat one), so it wins rather than stacking with it whenever two FormFields are adjacent
+   * siblings: Form's own direct children (a plain field list, no Card framing) or nested one
+   * level through CardContent (the common Card-framed, Save-button-capable case). This is what
+   * makes the rhythm hold regardless of DOM depth — the actual fix for gh#295. */
+  .ui-form-field + .ui-form-field {
+    margin-block-start: var(--form-field-row-gap);
   }
 
   /* Vertical (default + collapsed state): label stacked above the control column, LEFT-aligned.

package/dist/tokens/components/descriptions.css

@@ -6,4 +6,9 @@
    * A rem value gives a fixed aligned column; set `max-content` to size each label to its text.
    * (rule #44/#45 — a service theme tunes it here instead of forking CSS.) */
   --descriptions-label-width: 8rem;
+  /* Row-to-row gap (gh#294). Default = the historical hardcoded `gap-y-3`, so nothing changes
+   * visually by default. A consumer composing Descriptions beside a Form/FormField (a read-only
+   * block above an editable field on the same card) retunes this to `var(--space-4)` to match
+   * Form's own field-to-field rhythm instead of the two blocks reading as visually unrelated. */
+  --descriptions-row-gap: var(--space-3);
 }

package/dist/tokens/components/form.css

@@ -12,4 +12,16 @@
 
   /* Column gap between the label and its control in horizontal/inline layout. */
   --form-label-gap: var(--space-4); /* 16px */
+
+  /* Row rhythm between a Form's own top-level blocks (gh#295) — e.g. the field group's
+   * CardContent and its CardFooter action row, or two FormFields that happen to be Form's OWN
+   * direct children (no Card framing). Unchanged from the historical value. */
+  --form-block-gap: var(--space-4); /* 16px */
+
+  /* Field-to-field row rhythm (gh#295) — mirrors --descriptions-row-gap so a read-only value
+   * mixed in via `FormField.staticText` (gh#294) and a real Descriptions block share ONE canonical
+   * rhythm. Applied via margin-based sibling spacing on FormField itself (not Form's flex `gap`,
+   * which only reaches DIRECT children — dead in the common `Form > CardContent > FormField*`
+   * composition every real Save-button form needs), so it holds at any DOM depth relative to Form. */
+  --form-field-row-gap: var(--space-3); /* 12px */
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@godxjp/ui",
-  "version": "18.12.15",
-  "godxUiMcp": "18.12.15",
+  "version": "18.12.17",
+  "godxUiMcp": "18.12.17",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",