@astryxdesign/core 0.1.2 → 0.1.3-canary.6d57c8d

package/src/DateTimeInput/DateTimeInput.doc.mjs

@@ -7,7 +7,17 @@ export const docs = {
   displayName: 'Date Time Input',
   group: 'DateInput',
   category: 'Data Input',
-  keywords: ["datetimepicker","datetime","datepicker","timepicker","calendar","schedule","event","deadline","timestamp"],
+  keywords: [
+    'datetimepicker',
+    'datetime',
+    'datepicker',
+    'timepicker',
+    'calendar',
+    'schedule',
+    'event',
+    'deadline',
+    'timestamp',
+  ],
   props: [
     {
       name: 'label',
@@ -44,10 +54,17 @@ export const docs = {
       description: 'Disable the input and picker.',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the field focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled DateTimeInput in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+    },
     {
       name: 'value',
       type: 'ISODateTimeString',
-      description: 'Selected datetime in ISO 8601 format (YYYY-MM-DDTHH:MM or YYYY-MM-DDTHH:MM:SS).',
+      description:
+        'Selected datetime in ISO 8601 format (YYYY-MM-DDTHH:MM or YYYY-MM-DDTHH:MM:SS).',
     },
     {
       name: 'onChange',
@@ -58,28 +75,33 @@ export const docs = {
     {
       name: 'changeAction',
       type: '(value: ISODateTimeString | undefined) => void | Promise<void>',
-      description: 'Async action fired after onChange. Drives optimistic UI updates via useTransition.',
+      description:
+        'Async action fired after onChange. Drives optimistic UI updates via useTransition.',
     },
     {
       name: 'isLoading',
       type: 'boolean',
-      description: 'Whether the input is in a loading state. Disables interaction and shows a spinner.',
+      description:
+        'Whether the input is in a loading state. Disables interaction and shows a spinner.',
       default: 'false',
     },
     {
       name: 'min',
       type: 'ISODateTimeString',
-      description: 'Minimum selectable datetime. Constrains both date and time selection.',
+      description:
+        'Minimum selectable datetime. Constrains both date and time selection.',
     },
     {
       name: 'max',
       type: 'ISODateTimeString',
-      description: 'Maximum selectable datetime. Constrains both date and time selection.',
+      description:
+        'Maximum selectable datetime. Constrains both date and time selection.',
     },
     {
       name: 'dateConstraints',
       type: 'Array<(date: Date) => boolean>',
-      description: 'Array of custom constraint functions that disable specific dates.',
+      description:
+        'Array of custom constraint functions that disable specific dates.',
     },
     {
       name: 'hasSeconds',
@@ -90,13 +112,15 @@ export const docs = {
     {
       name: 'hourFormat',
       type: "'12h' | '24h'",
-      description: "Hour display format. '12h' shows AM/PM; '24h' uses 24-hour notation.",
+      description:
+        "Hour display format. '12h' shows AM/PM; '24h' uses 24-hour notation.",
       default: "'12h'",
     },
     {
       name: 'timeIncrement',
       type: 'number',
-      description: 'Minutes to add or subtract when using arrow keys in the time input.',
+      description:
+        'Minutes to add or subtract when using arrow keys in the time input.',
       default: '1',
     },
     {
@@ -108,9 +132,23 @@ export const docs = {
     {
       name: 'placeholder',
       type: 'string',
-      description: 'Placeholder text shown when no datetime is selected.',
+      description:
+        'Placeholder text shown in the date portion when no date is selected.',
       default: "'Select a date'",
     },
+    {
+      name: 'timePlaceholder',
+      type: 'string',
+      description:
+        'Placeholder text shown in the time portion when no time is selected.',
+      default: "'Select a time'",
+    },
+    {
+      name: 'timeLabel',
+      type: 'string',
+      description:
+        'Accessible label for the time portion. Defaults to "{label} time" so it is tied to the field label and localizable.',
+    },
     {
       name: 'size',
       type: "'sm' | 'md' | 'lg'",
@@ -120,12 +158,14 @@ export const docs = {
     {
       name: 'status',
       type: 'InputStatus',
-      description: 'Status indicator object for error, warning, or success states with a message.',
+      description:
+        'Status indicator object for error, warning, or success states with a message.',
     },
     {
       name: 'labelTooltip',
       type: 'string',
-      description: 'Tooltip text displayed via an info icon at the end of the label.',
+      description:
+        'Tooltip text displayed via an info icon at the end of the label.',
     },
     {
       name: 'numberOfMonths',
@@ -146,24 +186,90 @@ export const docs = {
     ],
   },
   usage: {
-    description: 'DateTimeInput combines a calendar popover with a time input for selecting both a date and time in a single interaction flow. Use it for scheduling, event creation, deadline setting, or any form field that needs a specific datetime.',
+    description:
+      'DateTimeInput combines a calendar popover with a time input for selecting both a date and time in a single interaction flow. Use it for scheduling, event creation, deadline setting, or any form field that needs a specific datetime.',
     bestPractices: [
-      { guidance: true, description: 'Provide clear labels and descriptions so users understand what datetime is expected.' },
-      { guidance: true, description: 'Use min and max to restrict selectable datetimes to valid ranges.' },
-      { guidance: true, description: 'Use hasClear when the datetime is optional so the user can reset it.' },
-      { guidance: true, description: "Choose the hour format (12h or 24h) that matches your audience's locale." },
-      { guidance: false, description: 'Use DateTimeInput when only a date is needed; use DateInput instead.' },
-      { guidance: false, description: 'Use DateTimeInput when only a time is needed; use TimeInput instead.' },
-      { guidance: false, description: 'Hide the label without surrounding context that makes the field purpose obvious.' },
+      {
+        guidance: true,
+        description:
+          'Provide clear labels and descriptions so users understand what datetime is expected.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use min and max to restrict selectable datetimes to valid ranges.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use hasClear when the datetime is optional so the user can reset it.',
+      },
+      {
+        guidance: true,
+        description:
+          "Choose the hour format (12h or 24h) that matches your audience's locale.",
+      },
+      {
+        guidance: false,
+        description:
+          'Use DateTimeInput when only a date is needed; use DateInput instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use DateTimeInput when only a time is needed; use TimeInput instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Hide the label without surrounding context that makes the field purpose obvious.',
+      },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled DateTimeInput in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
     anatomy: [
-      {name: 'Label', required: true, description: 'Text above the input describing what datetime is expected.'},
-      {name: 'Date input', required: true, description: 'A text input where the user can type a date. Clicking opens a calendar popover.'},
-      {name: 'Calendar icon', required: true, description: 'A button that opens the calendar popover.'},
-      {name: 'Calendar popover', required: false, description: 'A month grid that appears when the icon is clicked or the date input is focused.'},
-      {name: 'Time input', required: true, description: 'A text input for entering the time, displayed beside the date input.'},
-      {name: 'Clear button', required: false, description: 'A × button that resets the datetime value.'},
-      {name: 'Status message', required: false, description: 'An error, warning, or success message below the inputs.'},
+      {
+        name: 'Label',
+        required: true,
+        description:
+          'Text above the input describing what datetime is expected.',
+      },
+      {
+        name: 'Date input',
+        required: true,
+        description:
+          'A text input where the user can type a date. Clicking opens a calendar popover.',
+      },
+      {
+        name: 'Calendar icon',
+        required: true,
+        description: 'A button that opens the calendar popover.',
+      },
+      {
+        name: 'Calendar popover',
+        required: false,
+        description:
+          'A month grid that appears when the icon is clicked or the date input is focused.',
+      },
+      {
+        name: 'Time input',
+        required: true,
+        description:
+          'A text input for entering the time, displayed beside the date input.',
+      },
+      {
+        name: 'Clear button',
+        required: false,
+        description: 'A × button that resets the datetime value.',
+      },
+      {
+        name: 'Status message',
+        required: false,
+        description: 'An error, warning, or success message below the inputs.',
+      },
     ],
   },
 };
@@ -173,41 +279,196 @@ export const docsZh = {
   name: 'DateTimeInput',
   displayName: 'Date Time Input',
   usage: {
-    description: 'DateTimeInput combines a calendar popover with a time input for selecting both a date and time in a single interaction flow. Use it for scheduling, event creation, deadline setting, or any form field that needs a specific datetime.',
+    description:
+      'DateTimeInput combines a calendar popover with a time input for selecting both a date and time in a single interaction flow. Use it for scheduling, event creation, deadline setting, or any form field that needs a specific datetime.',
     bestPractices: [
-      { guidance: true, description: 'Provide clear labels and descriptions so users understand what datetime is expected.' },
-      { guidance: true, description: 'Use min and max to restrict selectable datetimes to valid ranges.' },
-      { guidance: true, description: 'Use hasClear when the datetime is optional so the user can reset it.' },
-      { guidance: true, description: "Choose the hour format (12h or 24h) that matches your audience's locale." },
-      { guidance: false, description: 'Use DateTimeInput when only a date is needed; use DateInput instead.' },
-      { guidance: false, description: 'Use DateTimeInput when only a time is needed; use TimeInput instead.' },
-      { guidance: false, description: 'Hide the label without surrounding context that makes the field purpose obvious.' },
+      {
+        guidance: true,
+        description:
+          'Provide clear labels and descriptions so users understand what datetime is expected.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use min and max to restrict selectable datetimes to valid ranges.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use hasClear when the datetime is optional so the user can reset it.',
+      },
+      {
+        guidance: true,
+        description:
+          "Choose the hour format (12h or 24h) that matches your audience's locale.",
+      },
+      {
+        guidance: false,
+        description:
+          'Use DateTimeInput when only a date is needed; use DateInput instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use DateTimeInput when only a time is needed; use TimeInput instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Hide the label without surrounding context that makes the field purpose obvious.',
+      },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled DateTimeInput in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
   },
   props: [
     {name: 'label', type: 'string', description: '标签文本。', required: true},
-    {name: 'isLabelHidden', type: 'boolean', description: '视觉隐藏标签。', default: 'false'},
-    {name: 'description', type: 'string', description: '显示在标签下方的辅助文本。'},
-    {name: 'isOptional', type: 'boolean', description: '在标签旁显示"(optional)"指示器。', default: 'false'},
-    {name: 'isRequired', type: 'boolean', description: '将字段标记为必填。', default: 'false'},
-    {name: 'isDisabled', type: 'boolean', description: '禁用输入框和选择器。', default: 'false'},
-    {name: 'value', type: 'ISODateTimeString', description: '选中的日期时间，ISO 8601 格式。'},
-    {name: 'onChange', type: '(value: ISODateTimeString | undefined) => void', description: '选中日期时间变更时调用的回调。', required: true},
-    {name: 'changeAction', type: '(value: ISODateTimeString | undefined) => void | Promise<void>', description: '在 onChange 之后触发的异步操作。通过 useTransition 驱动乐观更新。'},
-    {name: 'isLoading', type: 'boolean', description: '输入框是否处于加载状态。禁用交互并显示加载指示器。', default: 'false'},
-    {name: 'min', type: 'ISODateTimeString', description: '可选择的最早日期时间。同时约束日期和时间选择。'},
-    {name: 'max', type: 'ISODateTimeString', description: '可选择的最晚日期时间。同时约束日期和时间选择。'},
-    {name: 'dateConstraints', type: 'Array<(date: Date) => boolean>', description: '自定义约束函数数组，用于禁用特定日期。'},
-    {name: 'hasSeconds', type: 'boolean', description: '在时间部分包含秒。', default: 'false'},
-    {name: 'hourFormat', type: "'12h' | '24h'", description: "控制显示格式。'12h' 显示 AM/PM；'24h' 使用 24 小时制。", default: "'12h'"},
-    {name: 'timeIncrement', type: 'number', description: '在时间输入中按箭头键时增减的分钟数。', default: '1'},
-    {name: 'hasClear', type: 'boolean', description: '当有值时显示清除按钮。', default: 'false'},
-    {name: 'placeholder', type: 'string', description: '未选择日期时显示的占位符文本。', default: "'Select a date'"},
-    {name: 'size', type: "'sm' | 'md' | 'lg'", description: '输入控件的尺寸。', default: "'md'"},
-    {name: 'status', type: 'InputStatus', description: '错误、警告或成功状态的状态指示对象，附带消息。'},
-    {name: 'labelTooltip', type: 'string', description: '通过标签末尾的信息图标显示的提示文本。'},
-    {name: 'numberOfMonths', type: '1 | 2', description: '日历中同时显示的月份数量。', default: '1'},
-    {name: 'xstyle', type: 'StyleXStyles', description: '用于布局自定义的 StyleX 样式。必须是 stylex.create() 的值。'},
+    {
+      name: 'isLabelHidden',
+      type: 'boolean',
+      description: '视觉隐藏标签。',
+      default: 'false',
+    },
+    {
+      name: 'description',
+      type: 'string',
+      description: '显示在标签下方的辅助文本。',
+    },
+    {
+      name: 'isOptional',
+      type: 'boolean',
+      description: '在标签旁显示"(optional)"指示器。',
+      default: 'false',
+    },
+    {
+      name: 'isRequired',
+      type: 'boolean',
+      description: '将字段标记为必填。',
+      default: 'false',
+    },
+    {
+      name: 'isDisabled',
+      type: 'boolean',
+      description: '禁用输入框和选择器。',
+      default: 'false',
+    },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        '说明输入框为何被禁用。与 isDisabled 一起使用时，在悬停/键盘聚焦时显示提示，并通过 aria-disabled 保持日期和时间字段可聚焦（仍阻止输入和激活）。请使用此属性，而不是用 Tooltip 包裹已禁用的 DateTimeInput。',
+    },
+    {
+      name: 'value',
+      type: 'ISODateTimeString',
+      description: '选中的日期时间，ISO 8601 格式。',
+    },
+    {
+      name: 'onChange',
+      type: '(value: ISODateTimeString | undefined) => void',
+      description: '选中日期时间变更时调用的回调。',
+      required: true,
+    },
+    {
+      name: 'changeAction',
+      type: '(value: ISODateTimeString | undefined) => void | Promise<void>',
+      description:
+        '在 onChange 之后触发的异步操作。通过 useTransition 驱动乐观更新。',
+    },
+    {
+      name: 'isLoading',
+      type: 'boolean',
+      description: '输入框是否处于加载状态。禁用交互并显示加载指示器。',
+      default: 'false',
+    },
+    {
+      name: 'min',
+      type: 'ISODateTimeString',
+      description: '可选择的最早日期时间。同时约束日期和时间选择。',
+    },
+    {
+      name: 'max',
+      type: 'ISODateTimeString',
+      description: '可选择的最晚日期时间。同时约束日期和时间选择。',
+    },
+    {
+      name: 'dateConstraints',
+      type: 'Array<(date: Date) => boolean>',
+      description: '自定义约束函数数组，用于禁用特定日期。',
+    },
+    {
+      name: 'hasSeconds',
+      type: 'boolean',
+      description: '在时间部分包含秒。',
+      default: 'false',
+    },
+    {
+      name: 'hourFormat',
+      type: "'12h' | '24h'",
+      description: "控制显示格式。'12h' 显示 AM/PM；'24h' 使用 24 小时制。",
+      default: "'12h'",
+    },
+    {
+      name: 'timeIncrement',
+      type: 'number',
+      description: '在时间输入中按箭头键时增减的分钟数。',
+      default: '1',
+    },
+    {
+      name: 'hasClear',
+      type: 'boolean',
+      description: '当有值时显示清除按钮。',
+      default: 'false',
+    },
+    {
+      name: 'placeholder',
+      type: 'string',
+      description: '日期部分未选择日期时显示的占位符文本。',
+      default: "'Select a date'",
+    },
+    {
+      name: 'timePlaceholder',
+      type: 'string',
+      description: '时间部分未选择时间时显示的占位符文本。',
+      default: "'Select a time'",
+    },
+    {
+      name: 'timeLabel',
+      type: 'string',
+      description:
+        '时间部分的无障碍标签。默认为“{label} time”，与字段标签关联且可本地化。',
+    },
+    {
+      name: 'size',
+      type: "'sm' | 'md' | 'lg'",
+      description: '输入控件的尺寸。',
+      default: "'md'",
+    },
+    {
+      name: 'status',
+      type: 'InputStatus',
+      description: '错误、警告或成功状态的状态指示对象，附带消息。',
+    },
+    {
+      name: 'labelTooltip',
+      type: 'string',
+      description: '通过标签末尾的信息图标显示的提示文本。',
+    },
+    {
+      name: 'numberOfMonths',
+      type: '1 | 2',
+      description: '日历中同时显示的月份数量。',
+      default: '1',
+    },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description:
+        '用于布局自定义的 StyleX 样式。必须是 stylex.create() 的值。',
+    },
   ],
   theming: {
     targets: [
@@ -218,17 +479,52 @@ export const docsZh = {
 
 /** @type {import('../docs-types').TranslationDoc} */
 export const docsDense = {
-  description: 'combined date + time picker with calendar popover and time input',
+  description:
+    'combined date + time picker with calendar popover and time input',
   usage: {
-    description: 'DateTimeInput combines a calendar popover with a time input for selecting both a date and time. Use for scheduling, events, deadlines, or any form field needing a datetime.',
+    description:
+      'DateTimeInput combines a calendar popover with a time input for selecting both a date and time. Use for scheduling, events, deadlines, or any form field needing a datetime.',
     bestPractices: [
-      { guidance: true, description: 'Provide clear labels + descriptions so users understand what datetime is expected.' },
-      { guidance: true, description: 'Use min and max to restrict selectable datetimes to valid ranges.' },
-      { guidance: true, description: 'Use hasClear when the datetime is optional so the user can reset it.' },
-      { guidance: true, description: "Choose the hour format (12h or 24h) that matches your audience's locale." },
-      { guidance: false, description: 'Use DateTimeInput when only a date is needed; use DateInput instead.' },
-      { guidance: false, description: 'Use DateTimeInput when only a time is needed; use TimeInput instead.' },
-      { guidance: false, description: 'Hide the label without surrounding context that makes the field purpose obvious.' },
+      {
+        guidance: true,
+        description:
+          'Provide clear labels + descriptions so users understand what datetime is expected.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use min and max to restrict selectable datetimes to valid ranges.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use hasClear when the datetime is optional so the user can reset it.',
+      },
+      {
+        guidance: true,
+        description:
+          "Choose the hour format (12h or 24h) that matches your audience's locale.",
+      },
+      {
+        guidance: false,
+        description:
+          'Use DateTimeInput when only a date is needed; use DateInput instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use DateTimeInput when only a time is needed; use TimeInput instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Hide the label without surrounding context that makes the field purpose obvious.',
+      },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled DateTimeInput in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
   },
   propDescriptions: {
@@ -238,6 +534,8 @@ export const docsDense = {
     isOptional: 'show "(optional)" indicator',
     isRequired: 'mark field required',
     isDisabled: 'disable input+picker',
+    disabledMessage:
+      'reason shown in a tooltip on hover/focus when disabled; keeps fields focusable via aria-disabled',
     value: 'selected datetime ISO 8601',
     onChange: 'callback on datetime change',
     changeAction: 'async action after onChange; drives optimistic UI',
@@ -249,7 +547,10 @@ export const docsDense = {
     hourFormat: "display format. '12h' shows AM/PM; '24h' uses 24-hour",
     timeIncrement: 'minutes to add/subtract on arrow keys in time input',
     hasClear: 'Shows clear button when datetime is set',
-    placeholder: 'placeholder text when empty',
+    placeholder: 'date-portion placeholder when empty',
+    timePlaceholder: 'time-portion placeholder when empty',
+    timeLabel:
+      'accessible label for the time input; defaults to "{label} time"',
     size: 'input control size',
     status: 'error/warning/success status w/ message',
     labelTooltip: 'tooltip text via info icon at label end',