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.mdnew file mode 100644index 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.+@cixzhangdiff --git a/docs/specs/components/FileInput/FileInput.spec.md b/docs/specs/components/FileInput/FileInput.spec.mdindex 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 releaseConsumer 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 logdiff --git a/packages/core/src/FileInput/FileInput.doc.mjs b/packages/core/src/FileInput/FileInput.doc.mjsindex 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.tsxindex 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;