From 26f84f1bb1d0f73f6e117cbb9f4aabbfae610427 Mon Sep 17 00:00:00 2001
From: Seungwon Lee <seungwon@lablup.com>
Date: Thu, 8 Oct 2026 08:23:16 +0000
Subject: [PATCH 1/2] feat(Form): add a labelExtra slot to Form.Item's label
 row

Form.Item and FormItemVisual take `labelExtra` for actions that belong to a
field's label row (a filter or sort toggle). The slot renders beside the
<label>, not inside it, so its buttons stay out of the control's accessible
name and never trigger label activation. Vertical layout pushes it to the
far end of the row and stops the label column clipping its focus ring;
horizontal and inline layout put it right after the label, with the colon
moved to the end of the slot.

Requested by backend.ai-webui (lablup/backend.ai-webui#10094), whose session
launcher hand-built a button inside its label to get this.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  11 ++
 astryx/components/Form.doc.mjs                |   2 +-
 src/components/Form/FormItem.tsx              |   7 +
 src/components/Form/FormItemVisual.css        |  54 ++++++++
 .../Form/FormItemVisual.labelExtra.test.tsx   | 125 ++++++++++++++++++
 src/components/Form/FormItemVisual.tsx        |  22 +++
 6 files changed, 220 insertions(+), 1 deletion(-)
 create mode 100644 src/components/Form/FormItemVisual.labelExtra.test.tsx

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c33cd6e..f018d3c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,17 @@ Versioning follows the policy in [CONTRIBUTING.md](CONTRIBUTING.md#versioning).
 
 ## [Unreleased]
 
+### Added
+
+- **`Form.Item` / `FormItemVisual` take `labelExtra`** for actions that belong
+  to a field's label row, such as a filter or sort toggle. The slot
+  (`.uic-form-item__label-extra`) renders outside the `<label>`, so its
+  buttons stay out of the control's accessible name and never trigger label
+  activation. Vertical layout puts it at the far end of the row, and the label
+  column stops clipping so its focus ring stays whole. Horizontal and inline
+  layout put it right after the label, and the colon moves to the end of the
+  slot. Ignored without a `label`.
+
 ## [0.2.0-alpha.18]
 
 ### Added
diff --git a/astryx/components/Form.doc.mjs b/astryx/components/Form.doc.mjs
index b55456d..4e614ed 100644
--- a/astryx/components/Form.doc.mjs
+++ b/astryx/components/Form.doc.mjs
@@ -102,7 +102,7 @@ export default {
   ],
   usage: {
     description:
-      "Data-entry screens whose state, validation and submit need more than a few controlled fields. Style hooks: .uic-form-item and its __label, __control, __explain-error, __extra elements, and --form-item-margin-bottom, --form-item-gap and --form-item-line-height. Help, extra and the tooltip glyph take the theme's --color-text-description when it declares one (default --color-text-secondary). A control reaches its item's status through Form.Item.useStatus() or FormItemInputContext.",
+      "Data-entry screens whose state, validation and submit need more than a few controlled fields. Form.Item's labelExtra puts actions (a filter or sort toggle) in the label row, outside the <label> so they stay out of the control's accessible name: at the far end in vertical layout, right after the label otherwise. Style hooks: .uic-form-item and its __label, __label-extra, __control, __explain-error, __extra elements, and --form-item-margin-bottom, --form-item-gap and --form-item-line-height. Help, extra and the tooltip glyph take the theme's --color-text-description when it declares one (default --color-text-secondary). A control reaches its item's status through Form.Item.useStatus() or FormItemInputContext.",
   },
   examples: [
     {
diff --git a/src/components/Form/FormItem.tsx b/src/components/Form/FormItem.tsx
index 278ac3a..ae4a8f8 100644
--- a/src/components/Form/FormItem.tsx
+++ b/src/components/Form/FormItem.tsx
@@ -90,6 +90,11 @@ export interface FormItemProps<Values = any> extends Omit<
    * overlay and are ignored.
    */
   tooltip?: React.ReactNode | FormItemTooltipConfig;
+  /**
+   * Actions for the label row: far end in vertical layout, right after the
+   * label in horizontal / inline layout. Needs a `label`.
+   */
+  labelExtra?: React.ReactNode;
   extra?: React.ReactNode;
   /** `false` also suppresses meta bubbling to an ancestor item. */
   help?: React.ReactNode;
@@ -154,6 +159,7 @@ const FormItem = <Values,>(props: FormItemProps<Values>) => {
     name,
     label,
     tooltip,
+    labelExtra,
     extra,
     help,
     required,
@@ -333,6 +339,7 @@ const FormItem = <Values,>(props: FormItemProps<Values>) => {
           labelTitle={typeof label === "string" ? label : undefined}
           tooltip={normalizeTooltip(tooltip)}
           tooltipIcon={tooltipIcon(tooltip)}
+          labelExtra={labelExtra}
           extra={extra}
           help={help}
           required={mergedRequired}
diff --git a/src/components/Form/FormItemVisual.css b/src/components/Form/FormItemVisual.css
index 70314d8..7f80263 100644
--- a/src/components/Form/FormItemVisual.css
+++ b/src/components/Form/FormItemVisual.css
@@ -152,6 +152,60 @@
     visibility: hidden;
   }
 
+  /* `labelExtra`: the label column becomes a flex row and the colon moves from
+     the label to the end of the slot. Vertical pushes the slot to the far end. */
+  .uic-form-item__label-col[data-has-label-extra] {
+    display: flex;
+    align-items: center;
+    justify-content: flex-end;
+  }
+
+  .uic-form-item__label-col[data-has-label-extra][data-align="left"] {
+    justify-content: flex-start;
+  }
+
+  /* `overflow: visible` keeps the flush-right button's focus ring unclipped. */
+  .uic-form-item[data-layout="vertical"]
+    .uic-form-item__label-col[data-has-label-extra] {
+    justify-content: space-between;
+    overflow: visible;
+  }
+
+  .uic-form-item__label-col[data-has-label-extra] > .uic-form-item__label {
+    min-width: 0;
+  }
+
+  /* A too-narrow column clips the label text instead of painting it over the slot. */
+  .uic-form-item__label-col[data-has-label-extra]:not([data-wrap])
+    > .uic-form-item__label {
+    overflow: hidden;
+  }
+
+  .uic-form-item__label-col[data-has-label-extra] > .uic-form-item__label::after {
+    content: none;
+  }
+
+  .uic-form-item__label-extra {
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    margin-inline-start: var(--spacing-1);
+  }
+
+  .uic-form-item__label-extra::after {
+    content: ":";
+    margin-inline-start: var(--spacing-0-5);
+    margin-inline-end: var(--spacing-2);
+  }
+
+  .uic-form-item__label-extra[data-no-colon]::after {
+    content: "\a0";
+  }
+
+  .uic-form-item[data-layout="vertical"] .uic-form-item__label-extra::after {
+    content: none;
+  }
+
   .uic-form-item__optional {
     display: inline-block;
     margin-inline-start: var(--spacing-1);
diff --git a/src/components/Form/FormItemVisual.labelExtra.test.tsx b/src/components/Form/FormItemVisual.labelExtra.test.tsx
new file mode 100644
index 0000000..53df69b
--- /dev/null
+++ b/src/components/Form/FormItemVisual.labelExtra.test.tsx
@@ -0,0 +1,125 @@
+/**
+ * `labelExtra` renders in the label row but outside the `<label>`, so its
+ * actions stay out of the control's accessible name and never trigger label
+ * activation.
+ */
+import FormItemVisual from "./FormItemVisual";
+import { Form } from "./index";
+import { render, screen } from "@testing-library/react";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+describe("FormItemVisual — labelExtra", () => {
+  it("renders the slot in the label row, outside the <label>", () => {
+    render(
+      <FormItemVisual
+        label="Environments"
+        labelExtra={<button type="button">Filter</button>}
+      >
+        <input aria-label="environment" />
+      </FormItemVisual>,
+    );
+    const button = screen.getByRole("button", { name: "Filter" });
+    const slot = button.closest(".uic-form-item__label-extra");
+    expect(slot).not.toBeNull();
+    expect(button.closest("label")).toBeNull();
+    const labelCol = slot?.closest(".uic-form-item__label-col");
+    expect(labelCol?.hasAttribute("data-has-label-extra")).toBe(true);
+    expect(labelCol?.querySelector("label")?.textContent).toBe("Environments");
+  });
+
+  it("keeps the slot out of the control's accessible name", () => {
+    render(
+      <Form>
+        <Form.Item
+          name="environment"
+          label="Environments"
+          labelExtra={<button type="button">Filter</button>}
+        >
+          <input />
+        </Form.Item>
+      </Form>,
+    );
+    expect(screen.getByRole("textbox", { name: "Environments" })).not.toBeNull();
+  });
+
+  it("is forwarded by Form.Item", () => {
+    render(
+      <Form>
+        <Form.Item
+          name="environment"
+          label="Environments"
+          labelExtra={<button type="button">Filter</button>}
+        >
+          <input aria-label="environment" />
+        </Form.Item>
+      </Form>,
+    );
+    const button = screen.getByRole("button", { name: "Filter" });
+    expect(button.closest(".uic-form-item__label-extra")).not.toBeNull();
+  });
+
+  it("keeps the colon on the slot by default", () => {
+    render(
+      <FormItemVisual
+        layout="horizontal"
+        label="Environments"
+        labelExtra={<button type="button">Filter</button>}
+      >
+        <input aria-label="environment" />
+      </FormItemVisual>,
+    );
+    const slot = document.querySelector(".uic-form-item__label-extra");
+    expect(slot?.hasAttribute("data-no-colon")).toBe(false);
+  });
+
+  it("marks the slot as colon-less when the item has no colon", () => {
+    render(
+      <FormItemVisual
+        layout="horizontal"
+        colon={false}
+        label="Environments"
+        labelExtra={<button type="button">Filter</button>}
+      >
+        <input aria-label="environment" />
+      </FormItemVisual>,
+    );
+    const slot = document.querySelector(".uic-form-item__label-extra");
+    expect(slot?.hasAttribute("data-no-colon")).toBe(true);
+  });
+
+  it("renders no slot without a label", () => {
+    render(
+      <FormItemVisual labelExtra={<button type="button">Filter</button>}>
+        <input aria-label="environment" />
+      </FormItemVisual>,
+    );
+    expect(screen.queryByRole("button", { name: "Filter" })).toBeNull();
+  });
+
+  it.each([undefined, null, false])(
+    "renders no slot for labelExtra=%s",
+    (labelExtra) => {
+      render(
+        <FormItemVisual label="Environments" labelExtra={labelExtra}>
+          <input aria-label="environment" />
+        </FormItemVisual>,
+      );
+      expect(document.querySelector(".uic-form-item__label-extra")).toBeNull();
+      expect(
+        document
+          .querySelector(".uic-form-item__label-col")
+          ?.hasAttribute("data-has-label-extra"),
+      ).toBe(false);
+    },
+  );
+
+  // jsdom drops `@layer`, so the layout contract is read from the source.
+  it("spreads the row and unclips the focus ring in vertical layout", () => {
+    const css = readFileSync(join(__dirname, "FormItemVisual.css"), "utf8");
+    expect(css).toMatch(
+      /\[data-layout="vertical"\]\s+\.uic-form-item__label-col\[data-has-label-extra\]\s*\{[^}]*justify-content:\s*space-between;[^}]*overflow:\s*visible;/,
+    );
+  });
+});
diff --git a/src/components/Form/FormItemVisual.tsx b/src/components/Form/FormItemVisual.tsx
index 91d6959..06b9675 100644
--- a/src/components/Form/FormItemVisual.tsx
+++ b/src/components/Form/FormItemVisual.tsx
@@ -9,6 +9,7 @@
  *     .uic-form-item__row
  *       .uic-form-item__label-col
  *         label.uic-form-item__label        (+ .uic-form-item__tooltip)
+ *         .uic-form-item__label-extra
  *       .uic-form-item__control
  *         .uic-form-item__control-input
  *           .uic-form-item__control-input-content
@@ -50,6 +51,13 @@ export interface FormItemVisualProps {
   tooltip?: React.ReactNode;
   /** The tooltip trigger glyph. Defaults to a question mark in a circle. */
   tooltipIcon?: React.ReactNode;
+  /**
+   * Actions that belong to the label row (e.g. a filter button). Rendered
+   * outside the `<label>`, so they stay out of the control's accessible name:
+   * at the far end of the row in vertical layout, right after the label
+   * otherwise. Needs a `label`.
+   */
+  labelExtra?: React.ReactNode;
   extra?: React.ReactNode;
   help?: React.ReactNode;
   /** Renders the required marker. Independent of the `required` rule. */
@@ -116,6 +124,7 @@ export const FormItemVisual: React.FC<FormItemVisualProps> = ({
   labelTitle,
   tooltip,
   tooltipIcon,
+  labelExtra,
   extra,
   help,
   required,
@@ -168,12 +177,16 @@ export const FormItemVisual: React.FC<FormItemVisualProps> = ({
     setExtraHeight(extra && extraRef.current ? extraRef.current.clientHeight : 0);
   }, [extra]);
 
+  const hasLabelExtra =
+    labelExtra !== undefined && labelExtra !== null && labelExtra !== false;
+
   const labelNode =
     label === undefined || label === null ? null : (
       <div
         className={cx("uic-form-item__label-col", labelCol?.className)}
         data-align={labelAlign === "left" ? "left" : undefined}
         data-wrap={labelWrap ? "" : undefined}
+        data-has-label-extra={hasLabelExtra ? "" : undefined}
         style={colStyle(labelCol, "label")}
       >
         <label
@@ -205,6 +218,15 @@ export const FormItemVisual: React.FC<FormItemVisualProps> = ({
             </Tooltip>
           ) : null}
         </label>
+        {hasLabelExtra ? (
+          // The colon moves here so it still ends the row in horizontal layout.
+          <span
+            className="uic-form-item__label-extra"
+            data-no-colon={colon === false ? "" : undefined}
+          >
+            {labelExtra}
+          </span>
+        ) : null}
       </div>
     );
 

From 4e5005dd675f9c5163a39465b4905195ee616229 Mon Sep 17 00:00:00 2001
From: seungwon Lee <seungwon@lablup.com>
Date: Mon, 12 Oct 2026 18:09:54 +0900
Subject: [PATCH 2/2] docs(Form): add a labelExtra story

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/components/Form/Form.stories.tsx | 33 ++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/src/components/Form/Form.stories.tsx b/src/components/Form/Form.stories.tsx
index a016be4..af8ec88 100644
--- a/src/components/Form/Form.stories.tsx
+++ b/src/components/Form/Form.stories.tsx
@@ -187,6 +187,35 @@ function MembersForm(props: FormProps) {
   );
 }
 
+/** `labelExtra`: an action in the label row, outside the `<label>`. */
+function LabelExtraForm(props: FormProps) {
+  const [ascending, setAscending] = useState(true);
+  const options = ascending ? REGIONS : [...REGIONS].reverse();
+  return (
+    <Form layout="vertical" {...props} style={{ maxWidth: 480 }}>
+      <FormItem
+        name="region"
+        label="Region"
+        labelExtra={
+          <Button
+            variant="ghost"
+            size="sm"
+            label={ascending ? "Sort Z–A" : "Sort A–Z"}
+            onClick={() => setAscending((value) => !value)}
+          />
+        }
+      >
+        <Selector
+          label="Region"
+          isLabelHidden
+          options={options}
+          placeholder="Select a region"
+        />
+      </FormItem>
+    </Form>
+  );
+}
+
 const meta = {
   title: "Components/Form",
   // `Form` itself: its static members (`Form.Item`, ...) are not part of the props.
@@ -253,3 +282,7 @@ export const ItemVisual: Story = {
     </VStack>
   ),
 };
+
+export const LabelExtra: Story = {
+  render: (args) => <LabelExtraForm {...args} />,
+};