Skip to content

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

TypeScript

docs(useInputStatusIcon): add a minimal live example (#9714)

10k11ffd29c58bf21
diff --git a/.changeset/use-input-status-icon-coupon-example.md b/.changeset/use-input-status-icon-coupon-example.md
new file mode 100644
index 0000000000..99e4abba8b
--- /dev/null
+++ b/.changeset/use-input-status-icon-coupon-example.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[docs] A new `useInputStatusIcon — Coupon Code Status` example block shows a custom bordered input that takes its status affordance from `useInputStatusIcon`: a wrong code shows the error status and the valid code shows success, and the variant switch moves between a glyph with a message below (attached), no icon on the field (detached), and a focusable button with a tooltip that keyboard and screen-reader users can reach (tooltip). Copy it with `astryx template useInputStatusIconHookUsage <path>`.
+
+@10k11
diff --git a/apps/sandbox/scripts/next-export-routes.json b/apps/sandbox/scripts/next-export-routes.json
index 537c1e3094..13dc6d44a8 100644
--- a/apps/sandbox/scripts/next-export-routes.json
+++ b/apps/sandbox/scripts/next-export-routes.json
@@ -790,6 +790,7 @@
"/templates/useFocusTrapHookUsage/",
"/templates/useGridFocusHookUsage/",
"/templates/useHotkeysHookUsage/",
+ "/templates/useInputStatusIconHookUsage/",
"/templates/useKeyboardHintHookUsage/",
"/templates/useListFocusHookUsage/",
"/templates/useLocaleHookUsage/",
diff --git a/internal/shadcn-registry/routes.lock.json b/internal/shadcn-registry/routes.lock.json
index 73fd3c33ee..e846289e3d 100644
--- a/internal/shadcn-registry/routes.lock.json
+++ b/internal/shadcn-registry/routes.lock.json
@@ -3691,6 +3691,11 @@
"path": "examples/use-hover-card/profile-preview",
"aliases": []
},
+ {
+ "name": "example-use-input-status-icon-coupon-code-status",
+ "path": "examples/use-input-status-icon/coupon-code-status",
+ "aliases": []
+ },
{
"name": "example-use-keyboard-hint-arrow-key-hint",
"path": "examples/use-keyboard-hint/arrow-key-hint",
diff --git a/packages/cli/assets/templates/blocks/components/Hooks/useInputStatusIconHookUsage.doc.mjs b/packages/cli/assets/templates/blocks/components/Hooks/useInputStatusIconHookUsage.doc.mjs
new file mode 100644
index 0000000000..db3ce862a9
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Hooks/useInputStatusIconHookUsage.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'useInputStatusIcon',
+ name: 'useInputStatusIcon — Coupon Code Status',
+ displayName: 'useInputStatusIcon — Coupon Code Status',
+ description:
+ 'A custom bordered coupon-code input whose status affordance comes from useInputStatusIcon. A wrong code shows the error status and SAVE20 shows success. Switching the variant moves between a plain glyph with a message below (attached), no icon on the field (detached), and a focusable button whose tooltip keyboard and screen-reader users can reach, with its aria-describedby id returned by the hook (tooltip).',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Card', 'Field', 'SegmentedControl', 'Text', 'Layout'],
+};
diff --git a/packages/cli/assets/templates/blocks/components/Hooks/useInputStatusIconHookUsage.tsx b/packages/cli/assets/templates/blocks/components/Hooks/useInputStatusIconHookUsage.tsx
new file mode 100644
index 0000000000..3016febc63
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Hooks/useInputStatusIconHookUsage.tsx
@@ -0,0 +1,119 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useId, useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {Card} from '@astryxdesign/core/Card';
+import {
+ Field,
+ inputStatusBorderStyles,
+ inputWrapperStyles,
+} from '@astryxdesign/core/Field';
+import type {FieldStatusPlacement, InputStatus} from '@astryxdesign/core/Field';
+import {useInputStatusIcon} from '@astryxdesign/core/hooks';
+import {VStack} from '@astryxdesign/core/Layout';
+import {
+ SegmentedControl,
+ SegmentedControlItem,
+} from '@astryxdesign/core/SegmentedControl';
+import {Text} from '@astryxdesign/core/Text';
+import {colorVars, spacingVars} from '@astryxdesign/core/theme/tokens.stylex';
+
+const VALID_CODE = 'SAVE20';
+
+const styles = stylex.create({
+ field: {
+ paddingInline: spacingVars['--spacing-3'],
+ },
+ input: {
+ flexGrow: 1,
+ minWidth: 0,
+ borderWidth: 0,
+ backgroundColor: 'transparent',
+ color: colorVars['--color-text-primary'],
+ font: 'inherit',
+ outline: 'none',
+ },
+});
+
+function CouponField({statusVariant}: {statusVariant: FieldStatusPlacement}) {
+ const [code, setCode] = useState('SAVE10');
+ const inputId = useId();
+ const messageId = useId();
+
+ const status: InputStatus | undefined =
+ code === ''
+ ? undefined
+ : code.toUpperCase() === VALID_CODE
+ ? {type: 'success', message: 'Code applied: 20% off.'}
+ : {type: 'error', message: 'This code is not valid.'};
+
+ // The hook decides what the field shows for this status and variant, and
+ // returns the id of its tooltip only when that tooltip is in the DOM.
+ const {statusIcon, describedBy} = useInputStatusIcon({
+ status,
+ statusVariant,
+ });
+
+ // `attached` and `detached` carry the text in a message box under the field;
+ // `tooltip` carries it in the hook's tooltip instead.
+ const hasMessageBox =
+ statusVariant !== 'tooltip' && !!status && !!status.message;
+ const ariaDescribedBy =
+ [hasMessageBox ? messageId : null, describedBy].filter(Boolean).join(' ') ||
+ undefined;
+
+ return (
+ <Field
+ label="Coupon code"
+ isLabelHidden
+ inputID={inputId}
+ status={status && {...status, messageID: messageId}}
+ statusVariant={statusVariant}>
+ <div
+ {...stylex.props(
+ inputWrapperStyles.base,
+ styles.field,
+ status && inputStatusBorderStyles[status.type],
+ )}>
+ <input
+ id={inputId}
+ type="text"
+ aria-invalid={status?.type === 'error' || undefined}
+ aria-describedby={ariaDescribedBy}
+ placeholder="Enter a coupon code"
+ value={code}
+ onChange={e => setCode(e.target.value)}
+ {...stylex.props(styles.input)}
+ />
+ {statusIcon}
+ </div>
+ </Field>
+ );
+}
+
+export default function UseInputStatusIconHookUsage() {
+ const [statusVariant, setStatusVariant] =
+ useState<FieldStatusPlacement>('attached');
+
+ return (
+ <Card width={360} padding={4}>
+ <VStack gap={3}>
+ <SegmentedControl
+ label="Status variant"
+ value={statusVariant}
+ onChange={next => setStatusVariant(next as FieldStatusPlacement)}
+ size="sm">
+ <SegmentedControlItem value="attached" label="Attached" />
+ <SegmentedControlItem value="detached" label="Detached" />
+ <SegmentedControlItem value="tooltip" label="Tooltip" />
+ </SegmentedControl>
+ <CouponField statusVariant={statusVariant} />
+ <Text type="supporting">
+ Type {VALID_CODE} to see the success status.
+ </Text>
+ </VStack>
+ </Card>
+ );
+}
diff --git a/packages/cli/test/__golden__/no-icon-set/search-icon-set.json b/packages/cli/test/__golden__/no-icon-set/search-icon-set.json
index def019d8a7..bef00279f1 100644
--- a/packages/cli/test/__golden__/no-icon-set/search-icon-set.json
+++ b/packages/cli/test/__golden__/no-icon-set/search-icon-set.json
@@ -3,7 +3,7 @@
"type": "search",
"data": {
"query": "icon set",
- "matchCount": 376,
+ "matchCount": 377,
"results": [
{
"domain": "doc",
diff --git a/packages/cli/test/__golden__/no-icon-set/search-icon-set.txt b/packages/cli/test/__golden__/no-icon-set/search-icon-set.txt
index 09f6742a78..aaeb49cd9e 100644
--- a/packages/cli/test/__golden__/no-icon-set/search-icon-set.txt
+++ b/packages/cli/test/__golden__/no-icon-set/search-icon-set.txt
@@ -1,4 +1,4 @@
-Results for "icon set" (20 of 376)
+Results for "icon set" (20 of 377)
name: authoring/building-blocks/templates/build-the-template/template-assets/template-icons
section: use-astryx-icon
domain: doc
diff --git a/packages/cli/test/__golden__/no-icon-set/search-icon.json b/packages/cli/test/__golden__/no-icon-set/search-icon.json
index e1cd2f591b..04cc30f4c4 100644
--- a/packages/cli/test/__golden__/no-icon-set/search-icon.json
+++ b/packages/cli/test/__golden__/no-icon-set/search-icon.json
@@ -3,7 +3,7 @@
"type": "search",
"data": {
"query": "icon",
- "matchCount": 224,
+ "matchCount": 225,
"results": [
{
"domain": "component",
diff --git a/packages/cli/test/__golden__/no-icon-set/search-icon.txt b/packages/cli/test/__golden__/no-icon-set/search-icon.txt
index e262976dd8..cdb866cdc6 100644
--- a/packages/cli/test/__golden__/no-icon-set/search-icon.txt
+++ b/packages/cli/test/__golden__/no-icon-set/search-icon.txt
@@ -1,4 +1,4 @@
-Results for "icon" (20 of 224)
+Results for "icon" (20 of 225)
name: Icon
domain: component
package: @astryxdesign/core