ui: render exactly one element — move composition to components (field, toast, tabs)

lifeiscontent · lifeiscontent · commit c73cba7fc3b6 · 2026-06-28T16:24:43.000+07:00
A ui part renders a single element + {children}; composition is the components tier's job (rule 1/2).
- field: FieldLabel and FieldItemContent each became a single-element ui slot; the required-marker and
  label+description composition moved to new components/field ready-mades. Repointed the 4 field
  consumers + required-passing call sites.
- toast: the solid-* glyph assets + the tone-&gt;glyph map moved to components/toast; ui/toast keeps only
  the single-element styled status-icon slot (cva sizes/colors the svg child).
- tabs: the underline track+bar split into TabUnderlineBarTrack + TabUnderlineBar; the track-wraps-bar
  nesting moved into components/tabs (the underline Tab).
diff --git a/packages/propel/src/components/checkbox-field/checkbox-field.tsx b/packages/propel/src/components/checkbox-field/checkbox-field.tsx
@@ -7,8 +7,8 @@ import {
 import type { CheckboxTone } from "../../ui/checkbox/index";
 import { Field } from "../../ui/field/field";
 import { FieldItem } from "../../ui/field/field-item";
-import { FieldItemContent } from "../../ui/field/field-item-content";
 import type { FieldMagnitude } from "../../ui/field/variants";
+import { FieldItemContent } from "../field";
 import { FieldHelperText } from "../field/field-helper-text";
 
 export type CheckboxFieldProps = Omit<
diff --git a/packages/propel/src/components/checkbox-group-field/checkbox-group-field-option.tsx b/packages/propel/src/components/checkbox-group-field/checkbox-group-field-option.tsx
@@ -7,8 +7,8 @@ import {
 import { useFieldOptionMagnitude } from "../../internal/field-option-magnitude";
 import type { CheckboxTone } from "../../ui/checkbox/index";
 import { FieldItem } from "../../ui/field/field-item";
-import { FieldItemContent } from "../../ui/field/field-item-content";
 import type { FieldMagnitude } from "../../ui/field/variants";
+import { FieldItemContent } from "../field";
 
 export type CheckboxGroupFieldOptionProps = Omit<
   CheckboxFieldControlProps,
diff --git a/packages/propel/src/components/field/field-item-content.tsx b/packages/propel/src/components/field/field-item-content.tsx
@@ -0,0 +1,28 @@
+import type * as React from "react";
+
+import { FieldDescription } from "../../ui/field/field-description";
+import { FieldItemContent as FieldItemContentElement } from "../../ui/field/field-item-content";
+import { FieldLabel } from "../../ui/field/field-label";
+import { type InputMagnitude } from "../../ui/field/variants";
+
+/** The label + description column for a single choice option (checkbox/radio/switch row). */
+export function FieldItemContent({
+  children,
+  description,
+  magnitude,
+}: {
+  children: React.ReactNode;
+  description?: React.ReactNode;
+  magnitude: InputMagnitude;
+}) {
+  return (
+    <FieldItemContentElement>
+      <FieldLabel magnitude={magnitude} inset={false}>
+        {children}
+      </FieldLabel>
+      {description != null ? (
+        <FieldDescription magnitude={magnitude}>{description}</FieldDescription>
+      ) : null}
+    </FieldItemContentElement>
+  );
+}
diff --git a/packages/propel/src/components/field/field-label-group.tsx b/packages/propel/src/components/field/field-label-group.tsx
@@ -1,8 +1,9 @@
 import type * as React from "react";
 
-import { FieldDescription, FieldLabel } from "../../ui/field";
+import { FieldDescription } from "../../ui/field";
 import { FieldLabelGroup as FieldLabelGroupContainer } from "../../ui/field/field-label-group";
 import { type FieldLabelGroupVariantProps, type InputMagnitude } from "../../ui/field/variants";
+import { FieldLabel } from "./field-label";
 
 export type FieldLabelGroupProps = FieldLabelGroupVariantProps & {
   magnitude: InputMagnitude;
diff --git a/packages/propel/src/components/field/field-label.tsx b/packages/propel/src/components/field/field-label.tsx
@@ -0,0 +1,20 @@
+import {
+  FieldLabel as FieldLabelElement,
+  type FieldLabelProps as FieldLabelElementProps,
+} from "../../ui/field/field-label";
+import { FieldLabelRequiredMarker } from "../../ui/field/field-label-required-marker";
+
+export type FieldLabelProps = FieldLabelElementProps & { required?: boolean };
+
+/**
+ * The ready-made field label: the `FieldLabel` slot, plus a `FieldLabelRequiredMarker` when
+ * `required`.
+ */
+export function FieldLabel({ required, children, ...props }: FieldLabelProps) {
+  return (
+    <FieldLabelElement {...props}>
+      {children}
+      {required ? <FieldLabelRequiredMarker>*</FieldLabelRequiredMarker> : null}
+    </FieldLabelElement>
+  );
+}
diff --git a/packages/propel/src/components/field/index.tsx b/packages/propel/src/components/field/index.tsx
@@ -7,8 +7,8 @@ export {
   type FieldErrorProps,
   FieldItem,
   type FieldItemProps,
-  FieldLabel,
-  type FieldLabelProps,
 } from "../../ui/field/index";
+export * from "./field-item-content";
+export * from "./field-label";
 export * from "./field-helper-text";
 export * from "./field-label-group";
diff --git a/packages/propel/src/components/radio-group-field/radio-group-field-option.tsx b/packages/propel/src/components/radio-group-field/radio-group-field-option.tsx
@@ -2,8 +2,8 @@ import type * as React from "react";
 
 import { useFieldOptionMagnitude } from "../../internal/field-option-magnitude";
 import { FieldItem } from "../../ui/field/field-item";
-import { FieldItemContent } from "../../ui/field/field-item-content";
 import type { FieldMagnitude } from "../../ui/field/variants";
+import { FieldItemContent } from "../field";
 import { Radio, type RadioProps } from "../radio/radio";
 
 export type RadioGroupFieldOptionProps = RadioProps & {
diff --git a/packages/propel/src/components/switch-field/switch-field.tsx b/packages/propel/src/components/switch-field/switch-field.tsx
@@ -2,8 +2,8 @@ import type * as React from "react";
 
 import { Field } from "../../ui/field/field";
 import { FieldItem } from "../../ui/field/field-item";
-import { FieldItemContent } from "../../ui/field/field-item-content";
 import type { FieldMagnitude } from "../../ui/field/variants";
+import { FieldItemContent } from "../field";
 import { FieldHelperText } from "../field/field-helper-text";
 import { Switch, type SwitchMagnitude, type SwitchProps } from "../switch/index";
 
diff --git a/packages/propel/src/components/tabs/tab.tsx b/packages/propel/src/components/tabs/tab.tsx
@@ -5,6 +5,7 @@ import {
   Tab as TabElement,
   type TabProps as TabElementProps,
   TabUnderlineBar,
+  TabUnderlineBarTrack,
   TabUnderlineLabel,
 } from "../../ui/tabs";
 import { TabsAppearanceContext } from "./tabs-context";
@@ -33,7 +34,9 @@ export function Tab({ inlineStartNode, children, ...props }: TabProps) {
           {iconNode}
           {children}
         </TabUnderlineLabel>
-        <TabUnderlineBar />
+        <TabUnderlineBarTrack>
+          <TabUnderlineBar />
+        </TabUnderlineBarTrack>
       </TabElement>
     );
   }
diff --git a/packages/propel/src/components/toast/index.tsx b/packages/propel/src/components/toast/index.tsx
@@ -1,4 +1,5 @@
 export * from "./toast";
+export * from "./toast-status-icon";
 export * from "./toast-list";
 export * from "./toast-provider";
 
diff --git a/packages/propel/src/components/toast/solid-circle-alert.tsx b/packages/propel/src/components/toast/solid-circle-alert.tsx
diff --git a/packages/propel/src/components/toast/solid-circle-check.tsx b/packages/propel/src/components/toast/solid-circle-check.tsx
diff --git a/packages/propel/src/components/toast/solid-circle-x.tsx b/packages/propel/src/components/toast/solid-circle-x.tsx
diff --git a/packages/propel/src/components/toast/solid-icon.tsx b/packages/propel/src/components/toast/solid-icon.tsx
diff --git a/packages/propel/src/components/toast/solid-info.tsx b/packages/propel/src/components/toast/solid-info.tsx
diff --git a/packages/propel/src/components/toast/solid-triangle-alert.tsx b/packages/propel/src/components/toast/solid-triangle-alert.tsx
diff --git a/packages/propel/src/components/toast/toast-status-icon.tsx b/packages/propel/src/components/toast/toast-status-icon.tsx
@@ -0,0 +1,42 @@
+import type * as React from "react";
+
+import {
+  ToastStatusIcon as ToastStatusIconElement,
+  type ToastStatusIconProps as ToastStatusIconElementProps,
+  type ToastTone,
+} from "../../ui/toast";
+import { SolidCircleAlert } from "./solid-circle-alert";
+import { SolidCircleCheck } from "./solid-circle-check";
+import { SolidCircleX } from "./solid-circle-x";
+import type { StatusIconProps } from "./solid-icon";
+import { SolidInfo } from "./solid-info";
+import { SolidTriangleAlert } from "./solid-triangle-alert";
+
+type StatusGlyph = (props: StatusIconProps) => React.JSX.Element;
+
+// Each tone auto-selects a filled status glyph (see the solid-* assets) — the caller never
+// passes an icon. Filled glyphs match Figma's toast (node 1144-3158); lucide ships no filled
+// status equivalents, so these are hand-authored. The ui `ToastStatusIcon` slot owns the
+// `size-4 shrink-0` box + per-tone color; this ready-made owns only the tone→glyph mapping.
+const STATUS_ICON: Record<ToastTone, StatusGlyph> = {
+  success: SolidCircleCheck,
+  danger: SolidCircleX,
+  info: SolidInfo,
+  warning: SolidTriangleAlert,
+  neutral: SolidCircleAlert,
+};
+
+export type ToastStatusIconProps = Omit<ToastStatusIconElementProps, "children">;
+
+/**
+ * The tone-colored status icon at a toast's inline-start. Picks a filled glyph from `tone` and
+ * renders it inside the ui `ToastStatusIcon` slot, so consumers choose a `tone` and never an icon.
+ */
+export function ToastStatusIcon({ tone, ...props }: ToastStatusIconProps) {
+  const Glyph = STATUS_ICON[tone];
+  return (
+    <ToastStatusIconElement tone={tone} {...props}>
+      <Glyph />
+    </ToastStatusIconElement>
+  );
+}
diff --git a/packages/propel/src/components/toast/toast.tsx b/packages/propel/src/components/toast/toast.tsx
@@ -10,14 +10,14 @@ import {
   ToastClose,
   ToastContent,
   ToastDescription,
-  ToastStatusIcon,
   type ToastTone,
   ToastTextGroup,
   ToastTitle,
   createToastManager as createBaseToastManager,
   useToastManager,
 } from "../../ui/toast/index";
 import { LinearProgress } from "../linear-progress/index";
+import { ToastStatusIcon } from "./toast-status-icon";
 
 // The semantic intent of a toast (Figma "Property 1": Default / Variant2 / Variant3
 // = success / danger / info). `warning` and `neutral` round out the standard set.
diff --git a/packages/propel/src/ui/field/field-item-content.tsx b/packages/propel/src/ui/field/field-item-content.tsx
@@ -1,26 +1,13 @@
 import type * as React from "react";
 
-import { FieldDescription } from "./field-description";
-import { FieldLabel } from "./field-label";
-import { fieldItemContentVariants, type InputMagnitude } from "./variants";
+import { fieldItemContentVariants } from "./variants";
 
-export function FieldItemContent({
-  children,
-  description,
-  magnitude,
-}: {
-  children: React.ReactNode;
-  description?: React.ReactNode;
-  magnitude: InputMagnitude;
-}) {
-  return (
-    <div className={fieldItemContentVariants()}>
-      <FieldLabel magnitude={magnitude} inset={false}>
-        {children}
-      </FieldLabel>
-      {description != null ? (
-        <FieldDescription magnitude={magnitude}>{description}</FieldDescription>
-      ) : null}
-    </div>
-  );
+export type FieldItemContentProps = Omit<
+  React.ComponentPropsWithoutRef<"div">,
+  "className" | "style"
+>;
+
+/** The label + description column for a single choice option (checkbox/radio/switch row). */
+export function FieldItemContent(props: FieldItemContentProps) {
+  return <div className={fieldItemContentVariants()} {...props} />;
 }
diff --git a/packages/propel/src/ui/field/field-label.tsx b/packages/propel/src/ui/field/field-label.tsx
@@ -1,20 +1,11 @@
 import { Field as BaseField } from "@base-ui/react/field";
-import type * as React from "react";
 
-import { FieldLabelRequiredMarker } from "./field-label-required-marker";
 import { fieldLabelVariants, type FieldLabelVariantProps } from "./variants";
 
-export type FieldLabelProps = {
-  children: React.ReactNode;
-  required?: boolean;
-} & FieldLabelVariantProps;
+export type FieldLabelProps = Omit<BaseField.Label.Props, "className" | "style"> &
+  FieldLabelVariantProps;
 
-/** The label row: the label text, plus a `FieldLabelRequiredMarker` when `required`. */
-export function FieldLabel({ children, magnitude, required, inset }: FieldLabelProps) {
-  return (
-    <BaseField.Label className={fieldLabelVariants({ magnitude, inset })}>
-      {children}
-      {required ? <FieldLabelRequiredMarker>*</FieldLabelRequiredMarker> : null}
-    </BaseField.Label>
-  );
+/** The label naming a field's control. */
+export function FieldLabel({ magnitude, inset, ...props }: FieldLabelProps) {
+  return <BaseField.Label className={fieldLabelVariants({ magnitude, inset })} {...props} />;
 }
diff --git a/packages/propel/src/ui/field/field.stories.tsx b/packages/propel/src/ui/field/field.stories.tsx
@@ -32,13 +32,13 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 /**
- * A labeled input with helper text, assembled from the atomic parts. `FieldLabel required` appends
- * the `FieldLabelRequiredMarker` slot, passing the asterisk glyph in as its child.
+ * A labeled input with helper text, assembled from the atomic parts. The `FieldLabel` slot names
+ * the control; the `RequiredMarker` story shows how to append the `FieldLabelRequiredMarker` slot.
  */
 export const Default: Story = {
   render: () => (
     <Field name="displayName">
-      <FieldLabel magnitude="md" required inset={false}>
+      <FieldLabel magnitude="md" inset={false}>
         Display name
       </FieldLabel>
       <Input magnitude="md" required placeholder="Ada Lovelace" />
diff --git a/packages/propel/src/ui/tabs/index.tsx b/packages/propel/src/ui/tabs/index.tsx
@@ -1,5 +1,6 @@
 export * from "./tab";
 export * from "./tab-underline-bar";
+export * from "./tab-underline-bar-track";
 export * from "./tab-underline-label";
 export * from "./tabs";
 export * from "./tabs-indicator";
diff --git a/packages/propel/src/ui/tabs/tab-underline-bar-track.tsx b/packages/propel/src/ui/tabs/tab-underline-bar-track.tsx
@@ -0,0 +1,17 @@
+import type * as React from "react";
+
+import { underlineBarTrackVariants } from "./variants";
+
+export type TabUnderlineBarTrackProps = Omit<
+  React.ComponentPropsWithoutRef<"span">,
+  "className" | "style"
+>;
+
+/**
+ * The padded track that holds an `underline`-appearance tab's sliding bar. Renders its bar child
+ * via `{...props}` so the underline track cva stays internal; compose `<TabUnderlineBar />` inside
+ * it.
+ */
+export function TabUnderlineBarTrack(props: TabUnderlineBarTrackProps) {
+  return <span className={underlineBarTrackVariants()} {...props} />;
+}
diff --git a/packages/propel/src/ui/tabs/tab-underline-bar.tsx b/packages/propel/src/ui/tabs/tab-underline-bar.tsx
@@ -1,14 +1,17 @@
-import { underlineBarTrackVariants, underlineBarVariants } from "./variants";
+import type * as React from "react";
+
+import { underlineBarVariants } from "./variants";
+
+export type TabUnderlineBarProps = Omit<
+  React.ComponentPropsWithoutRef<"span">,
+  "className" | "style"
+>;
 
 /**
- * The sliding underline beneath an `underline`-appearance tab's label: a padded track containing
- * the decorative bar that tints on hover and goes transparent when active (the shared
- * `TabsIndicator` takes over). Owns both styled `<span>`s so the underline cva stays internal.
+ * The decorative bar beneath an `underline`-appearance tab's label: tints on hover and goes
+ * transparent when active (the shared `TabsIndicator` takes over). Sits inside a
+ * `TabUnderlineBarTrack`. Owns the styled `<span>` so the underline cva stays internal.
  */
-export function TabUnderlineBar() {
-  return (
-    <span className={underlineBarTrackVariants()}>
-      <span aria-hidden className={underlineBarVariants()} />
-    </span>
-  );
+export function TabUnderlineBar(props: TabUnderlineBarProps) {
+  return <span aria-hidden className={underlineBarVariants()} {...props} />;
 }
diff --git a/packages/propel/src/ui/tabs/tabs.stories.tsx b/packages/propel/src/ui/tabs/tabs.stories.tsx
@@ -4,6 +4,7 @@ import { expect } from "storybook/test";
 import {
   Tab,
   TabUnderlineBar,
+  TabUnderlineBarTrack,
   TabUnderlineLabel,
   Tabs,
   TabsIndicator,
@@ -61,7 +62,8 @@ export const Default: Story = {
 /**
  * The underline appearance: compose the shared `TabsIndicator` inside the `TabsList` (the
  * ready-made `components/tabs` adds it for you). Each `Tab` decorates its body with the atomic
- * `TabUnderlineLabel` (the rounded label box) and `TabUnderlineBar` (the per-tab hover bar).
+ * `TabUnderlineLabel` (the rounded label box) and a `TabUnderlineBarTrack` wrapping a
+ * `TabUnderlineBar` (the padded track plus the per-tab hover bar).
  */
 export const Underline: Story = {
   render: () => (
@@ -70,7 +72,9 @@ export const Underline: Story = {
         {TAB_ITEMS.map((item) => (
           <Tab key={item.value} appearance="underline" value={item.value}>
             <TabUnderlineLabel>{item.label}</TabUnderlineLabel>
-            <TabUnderlineBar />
+            <TabUnderlineBarTrack>
+              <TabUnderlineBar />
+            </TabUnderlineBarTrack>
           </Tab>
         ))}
         <TabsIndicator />
diff --git a/packages/propel/src/ui/toast/toast-status-icon.tsx b/packages/propel/src/ui/toast/toast-status-icon.tsx
diff --git a/packages/propel/src/ui/toast/toast.stories.tsx b/packages/propel/src/ui/toast/toast.stories.tsx
diff --git a/packages/propel/src/ui/toast/variants.ts b/packages/propel/src/ui/toast/variants.ts

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`export * from "./toast";`
	`2`	`+export * from "./toast-status-icon";`
`2`	`3`	`export * from "./toast-list";`
`3`	`4`	`export * from "./toast-provider";`
`4`	`5`