Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(FileInput): dropzone mode does not offer attached status placement (#9258)

Cindy Zhang554e9bc14566
diff --git a/.changeset/fileinput-dropzone-status-variant-docs.md b/.changeset/fileinput-dropzone-status-variant-docs.md
new file mode 100644
index 0000000000..c374e9ef22
--- /dev/null
+++ b/.changeset/fileinput-dropzone-status-variant-docs.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[docs] FileInput's `statusVariant` docs say that dropzone mode does not support `attached`; use `detached` or `tooltip` there. Rendering is unchanged in this release. From the next minor release, a dropzone resolves `attached` to `detached` and defaults to it.
+@cixzhang
diff --git a/docs/specs/components/FileInput/FileInput.spec.md b/docs/specs/components/FileInput/FileInput.spec.md
index 1a6bbd4db7..dc334e1a9a 100644
--- a/docs/specs/components/FileInput/FileInput.spec.md
+++ b/docs/specs/components/FileInput/FileInput.spec.md
@@ -39,6 +39,9 @@ ownership for the upload affordance that FileInput paints through Icon.
runtime default, DOM, prop, interaction, or accessibility behavior changes
- Controlled/uncontrolled behavior: unchanged; FileInput remains controlled
- Migration decision: `component:FileInput/DEC-1`
+- Dropzone status placement (FR6): the docs mark `attached` unsupported in
+ dropzone mode, and the released `attached` rendering stays until the next
+ minor release
Consumer migration instructions belong in consumer docs and release notes.
@@ -68,13 +71,14 @@ its `mode` and `status` axes.
## Behavioral and layout contract
-| ID | Candidate invariant | Basis | Review state |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------- |
-| FR1 | The visible selection surface carries `file-input` and reflects the existing `mode` and resolved status. | Current source, public docs, and focused tests | Verified current behavior |
-| FR2 | When not loading, input mode renders an upload affordance at the small Icon size. Dropzone mode renders it at the medium Icon size only while no file is selected. | Current source and focused tests | Verified current behavior |
-| FR3 | Icon owns the rendered glyph's base size, color, and accessibility semantics; FileInput owns the affordance's mode-dependent placement and default size. | Current composition and component boundaries | Verified current composition |
-| FR4 | The rendered upload affordance MUST carry `file-input-icon` with the existing `mode` reflected, so a theme can restyle the glyph box without structural selectors or changing every Icon that uses the same artwork. | Owner-approved target contract | Approved additive contract |
-| FR5 | Adding the target MUST NOT change the default artwork, computed layout, interaction, file-selection behavior, accessible name, or decorative Icon semantics. | Compatibility policy and focused regression tests | Required compatibility behavior |
+| ID | Candidate invariant | Basis | Review state |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------- |
+| FR1 | The visible selection surface carries `file-input` and reflects the existing `mode` and resolved status. | Current source, public docs, and focused tests | Verified current behavior |
+| FR2 | When not loading, input mode renders an upload affordance at the small Icon size. Dropzone mode renders it at the medium Icon size only while no file is selected. | Current source and focused tests | Verified current behavior |
+| FR3 | Icon owns the rendered glyph's base size, color, and accessibility semantics; FileInput owns the affordance's mode-dependent placement and default size. | Current composition and component boundaries | Verified current composition |
+| FR4 | The rendered upload affordance MUST carry `file-input-icon` with the existing `mode` reflected, so a theme can restyle the glyph box without structural selectors or changing every Icon that uses the same artwork. | Owner-approved target contract | Approved additive contract |
+| FR5 | Adding the target MUST NOT change the default artwork, computed layout, interaction, file-selection behavior, accessible name, or decorative Icon semantics. | Compatibility policy and focused regression tests | Required compatibility behavior |
+| FR6 | Dropzone mode does not offer `attached` status placement: its tall, custom surface cannot meet the attached conditions of `family:input-fields` FR8, so under AV6 it offers `detached` and `tooltip`. Dropzone resolves `attached` to `detached` and defaults to `detached` from the next minor release; until then the released `attached` rendering is kept. Input mode keeps `attached` as its default. | `family:input-fields` FR8, AV6, and its status placement conformance note | Approved; rendering change at the next minor |
### Allowed variation
@@ -171,11 +175,12 @@ target owns only this stable upload position and its existing mode distinction.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ------------------- | ----------------------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------- |
-| FR1, FR2 | `FileInput.test.tsx` rendering and target suites | Input/dropzone; empty/selected/loading | Moving the root target or changing when/at what size the affordance renders breaks focused assertions. | `audit:FileInput/theming` |
-| FR3, FR4, FR5 | `FileInput.test.tsx`, `themingTargets.test.ts`, probe-theme check | Both modes and same-element Icon target | Missing the target, reflecting the wrong mode, or moving it off the glyph fails source/docs/probe coverage. | `audit:FileInput/theming` |
-| Theming anatomy map | `scripts/check-knowledge.mjs` | Nine anatomy entries and two locally owned targets | Missing, extra, prefixed, stale, or unclaimed current mappings fail validation. | `audit:FileInput/anatomy` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------- |
+| FR1, FR2 | `FileInput.test.tsx` rendering and target suites | Input/dropzone; empty/selected/loading | Moving the root target or changing when/at what size the affordance renders breaks focused assertions. | `audit:FileInput/theming` |
+| FR3, FR4, FR5 | `FileInput.test.tsx`, `themingTargets.test.ts`, probe-theme check | Both modes and same-element Icon target | Missing the target, reflecting the wrong mode, or moving it off the glyph fails source/docs/probe coverage. | `audit:FileInput/theming` |
+| FR6 | `FileInput.doc.mjs` `statusVariant` entry and the prop's JSDoc in `FileInput.tsx` | Dropzone and input modes | A doc or JSDoc that offers `attached` in dropzone mode, or drops it from input mode, fails review. | — |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Nine anatomy entries and two locally owned targets | Missing, extra, prefixed, stale, or unclaimed current mappings fail validation. | `audit:FileInput/anatomy` |
## Decision log
diff --git a/packages/core/src/FileInput/FileInput.doc.mjs b/packages/core/src/FileInput/FileInput.doc.mjs
index b5d032ee68..3ea349162c 100644
--- a/packages/core/src/FileInput/FileInput.doc.mjs
+++ b/packages/core/src/FileInput/FileInput.doc.mjs
@@ -123,7 +123,7 @@ export const docs = {
name: 'statusVariant',
type: "'attached' | 'detached' | 'tooltip'",
description:
- 'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing; tooltip hides the message box and surfaces it in a tooltip on the status icon.',
+ 'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing; tooltip hides the message box and surfaces it in a tooltip on the status icon. Dropzone mode does not support attached: use detached or tooltip. From the next minor release, a dropzone resolves attached to detached and defaults to it.',
default: "'attached'",
},
{
@@ -296,7 +296,7 @@ export const docsZh = {
name: 'statusVariant',
type: "'attached' | 'detached' | 'tooltip'",
description:
- '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方(带边框处理);detached 作为独立元素浮于下方并留有间距;tooltip 隐藏消息框,并在状态图标上以提示气泡形式显示。',
+ '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方(带边框处理);detached 作为独立元素浮于下方并留有间距;tooltip 隐藏消息框,并在状态图标上以提示气泡形式显示。dropzone 模式不支持 attached:请使用 detached 或 tooltip。从下一个次版本起,dropzone 会将 attached 解析为 detached,并以其为默认值。',
default: "'attached'",
},
{
@@ -408,7 +408,7 @@ export const docsDense = {
placeholder: 'Placeholder when no files selected.',
mode: "Visual mode: 'input' (compact) or 'dropzone' (drag-and-drop).",
status: 'Validation status; colored border. Message floats below.',
- statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',
+ statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon. Dropzone: attached unsupported; use detached or tooltip (detached default from next minor).',
labelTooltip: 'Tooltip in info icon at label end.',
},
};
diff --git a/packages/core/src/FileInput/FileInput.tsx b/packages/core/src/FileInput/FileInput.tsx
index 03fee9b3a9..443c6aac2c 100644
--- a/packages/core/src/FileInput/FileInput.tsx
+++ b/packages/core/src/FileInput/FileInput.tsx
@@ -404,6 +404,10 @@ export interface FileInputProps extends Omit<
* - 'attached': message overlaps directly below the input (bordered treatment)
* - 'detached': message floats below as a separate element with spacing
* - 'tooltip': no message box; the status icon becomes a focusable info-tip button that reveals the message on hover, keyboard focus, or tap
+ *
+ * Dropzone mode does not support 'attached': its tall surface cannot carry an
+ * overlapping message. Use 'detached' or 'tooltip' there. From the next minor
+ * release, a dropzone resolves 'attached' to 'detached' and defaults to it.
* @default 'attached'
*/
statusVariant?: FieldStatusPlacement;