@astryxdesign/core 0.0.0-bootstrap.0 → 0.1.0-canary.08d4cf4

package/src/Timestamp/Timestamp.tsx

@@ -0,0 +1,425 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file Timestamp.tsx
+ * @input Uses React, Intl.DateTimeFormat, Text
+ * @output Exports Timestamp component and related types
+ * @position Core implementation; renders formatted timestamps
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Timestamp/Timestamp.doc.mjs
+ * - /packages/core/src/Timestamp/Timestamp.test.tsx
+ * - /packages/core/src/Timestamp/index.ts
+ * - /apps/storybook/stories/Timestamp.stories.tsx
+ * - /packages/cli/templates/blocks/components/Timestamp/ (showcase blocks)
+ */
+
+import {useEffect, useRef, useState, lazy, Suspense} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {Text} from '../Text';
+import type {
+  TextType,
+  TextSize,
+  TextColor,
+  TextWeight,
+} from '../theme/types';
+import {mergeProps, mergeRefs} from '../utils';
+import type {BaseProps} from '../BaseProps';
+import {themeProps} from '../utils/themeProps';
+
+const LazyXDSTooltip = lazy(async () =>
+  import('../Tooltip/Tooltip').then(mod => ({default: mod.Tooltip})),
+);
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type TimestampFormat =
+  | 'relative'
+  | 'auto'
+  | 'date'
+  | 'date_time'
+  | 'time'
+  | 'system_date'
+  | 'system_date_time'
+  | 'system_time';
+
+export interface TimestampProps extends BaseProps<HTMLTimeElement> {
+  /** Ref forwarded to the root `<time>` element. */
+  ref?: React.Ref<HTMLTimeElement>;
+  /** The date/time to display. Accepts Unix timestamps (seconds) or ISO 8601 strings. */
+  value: string | number;
+  /**
+   * Display format.
+   * - `'relative'`: "2 hours ago", "yesterday", "just now"
+   * - `'auto'`: Relative for recent times, `date_time` for older
+   * - `'date'`: "Mar 21, 2025"
+   * - `'date_time'`: "Mar 21, 2025, 2:51 PM"
+   * - `'time'`: "2:51 PM"
+   * - `'system_date'`: "2025-03-21"
+   * - `'system_date_time'`: "2025-03-21 14:51:53"
+   * - `'system_time'`: "14:51:53"
+   * @default 'auto'
+   */
+  format?: TimestampFormat;
+  /**
+   * Threshold in seconds for 'auto' format to switch from relative to date_time.
+   * @default 604800 (7 days)
+   */
+  autoThreshold?: number;
+  /**
+   * Whether to show a tooltip with the full date/time on hover.
+   * @default true
+   */
+  hasTooltip?: boolean;
+  /**
+   * Whether to append the timezone abbreviation after the timestamp.
+   * Applies to date_time, time, system_date_time, and system_time formats.
+   * @default false
+   */
+  isTimezoneShown?: boolean;
+  /**
+   * Whether the relative time should update live.
+   * @default false
+   */
+  isLive?: boolean;
+  /**
+   * Semantic text type. Determines size, weight, and line-height from theme.
+   * @default 'supporting'
+   */
+  type?: TextType;
+  /**
+   * Explicit font size override. Overrides the size from `type`.
+   */
+  size?: TextSize;
+  /**
+   * Text color.
+   * @default 'secondary'
+   */
+  color?: TextColor;
+  /**
+   * Font weight override.
+   */
+  weight?: TextWeight;
+  /** Test ID for testing frameworks. */
+  'data-testid'?: string;
+}
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+  time: {
+    display: 'inline',
+    fontFamily: 'inherit',
+    fontStyle: 'normal',
+    // Reset <time> element defaults
+    fontSize: 'inherit',
+    lineHeight: 'inherit',
+    color: 'inherit',
+    fontWeight: 'inherit',
+  },
+});
+
+// =============================================================================
+// Formatting utilities
+// =============================================================================
+
+const MINUTE = 60;
+const HOUR = 3600;
+const DAY = 86400;
+const MONTH = 30 * DAY;
+const YEAR = 365 * DAY;
+
+/** Default auto threshold: 7 days in seconds */
+const DEFAULT_AUTO_THRESHOLD = 7 * DAY;
+
+function parseValue(value: string | number): Date {
+  if (typeof value === 'number') {
+    // Heuristic: if the number is less than 1e12, treat as seconds; otherwise ms.
+    // Unix timestamps in seconds are < 1e12 until ~2286.
+    return new Date(value < 1e12 ? value * 1000 : value);
+  }
+  return new Date(value);
+}
+
+function getRelativeTimeString(date: Date, now: Date): string {
+  const diffSeconds = Math.round((now.getTime() - date.getTime()) / 1000);
+
+  if (diffSeconds < 0) {
+    // Future dates
+    const absDiff = Math.abs(diffSeconds);
+    if (absDiff < MINUTE) {
+      return 'in a few seconds';
+    }
+    if (absDiff < HOUR) {
+      const mins = Math.round(absDiff / MINUTE);
+      return `in ${mins} ${mins === 1 ? 'minute' : 'minutes'}`;
+    }
+    if (absDiff < DAY) {
+      const hours = Math.round(absDiff / HOUR);
+      return `in ${hours} ${hours === 1 ? 'hour' : 'hours'}`;
+    }
+    if (absDiff < MONTH) {
+      const days = Math.round(absDiff / DAY);
+      return `in ${days} ${days === 1 ? 'day' : 'days'}`;
+    }
+    if (absDiff < YEAR) {
+      const months = Math.round(absDiff / MONTH);
+      return `in ${months} ${months === 1 ? 'month' : 'months'}`;
+    }
+    const years = Math.round(absDiff / YEAR);
+    return `in ${years} ${years === 1 ? 'year' : 'years'}`;
+  }
+
+  if (diffSeconds < 10) {
+    return 'just now';
+  }
+  if (diffSeconds < MINUTE) {
+    return `${diffSeconds} seconds ago`;
+  }
+  if (diffSeconds < HOUR) {
+    const mins = Math.round(diffSeconds / MINUTE);
+    return `${mins} ${mins === 1 ? 'minute' : 'minutes'} ago`;
+  }
+  if (diffSeconds < DAY) {
+    const hours = Math.round(diffSeconds / HOUR);
+    return `${hours} ${hours === 1 ? 'hour' : 'hours'} ago`;
+  }
+  if (diffSeconds < 2 * DAY) {
+    return 'yesterday';
+  }
+  if (diffSeconds < MONTH) {
+    const days = Math.round(diffSeconds / DAY);
+    return `${days} days ago`;
+  }
+  if (diffSeconds < YEAR) {
+    const months = Math.round(diffSeconds / MONTH);
+    return `${months} ${months === 1 ? 'month' : 'months'} ago`;
+  }
+  const years = Math.round(diffSeconds / YEAR);
+  return `${years} ${years === 1 ? 'year' : 'years'} ago`;
+}
+
+function pad(n: number): string {
+  return String(n).padStart(2, '0');
+}
+
+function formatTimestamp(
+  date: Date,
+  format: Exclude<TimestampFormat, 'relative' | 'auto'>,
+  isTimezoneShown: boolean,
+): string {
+  switch (format) {
+    case 'date':
+      return new Intl.DateTimeFormat(undefined, {
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+      }).format(date);
+
+    case 'date_time':
+      return new Intl.DateTimeFormat(undefined, {
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+        hour: 'numeric',
+        minute: '2-digit',
+        ...(isTimezoneShown ? {timeZoneName: 'short'} : {}),
+      }).format(date);
+
+    case 'time':
+      return new Intl.DateTimeFormat(undefined, {
+        hour: 'numeric',
+        minute: '2-digit',
+        ...(isTimezoneShown ? {timeZoneName: 'short'} : {}),
+      }).format(date);
+
+    case 'system_date': {
+      const y = date.getFullYear();
+      const m = pad(date.getMonth() + 1);
+      const d = pad(date.getDate());
+      return `${y}-${m}-${d}`;
+    }
+
+    case 'system_date_time': {
+      const y = date.getFullYear();
+      const m = pad(date.getMonth() + 1);
+      const d = pad(date.getDate());
+      const h = pad(date.getHours());
+      const min = pad(date.getMinutes());
+      const s = pad(date.getSeconds());
+      return `${y}-${m}-${d} ${h}:${min}:${s}`;
+    }
+
+    case 'system_time': {
+      const h = pad(date.getHours());
+      const min = pad(date.getMinutes());
+      const s = pad(date.getSeconds());
+      return `${h}:${min}:${s}`;
+    }
+  }
+}
+
+function getFullAbsoluteString(date: Date): string {
+  return new Intl.DateTimeFormat(undefined, {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+    hour: 'numeric',
+    minute: '2-digit',
+    second: '2-digit',
+    timeZoneName: 'short',
+  }).format(date);
+}
+
+/** Returns the interval (in ms) at which a relative timestamp should update. */
+function getLiveInterval(diffSeconds: number): number {
+  const absDiff = Math.abs(diffSeconds);
+  if (absDiff < MINUTE) {
+    return 1000;
+  } // every second
+  if (absDiff < HOUR) {
+    return 30_000;
+  } // every 30s
+  if (absDiff < DAY) {
+    return 60_000;
+  } // every minute
+  return 300_000; // every 5 minutes
+}
+
+/** Whether a format is non-relative (i.e. shows a fixed date/time). */
+function isAbsoluteFormat(
+  format: TimestampFormat,
+): format is Exclude<TimestampFormat, 'relative' | 'auto'> {
+  return format !== 'relative' && format !== 'auto';
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Displays a formatted timestamp as human-readable text.
+ *
+ * Renders a semantic `<time>` element with an ISO 8601 `datetime` attribute,
+ * styled via Text. Supports relative ("2 hours ago"), multiple absolute
+ * formats, and auto formatting. Optionally shows a tooltip with the full
+ * absolute time and can update live.
+ *
+ * @example
+ * ```
+ * <Timestamp value="2026-02-19T17:00:00Z" />
+ * <Timestamp value={1740000000} format="date" />
+ * <Timestamp value={date} format="auto" isLive />
+ * <Timestamp value={event.timestamp} format="system_date_time" />
+ * ```
+ */
+export function Timestamp({
+  value,
+  format = 'auto',
+  autoThreshold = DEFAULT_AUTO_THRESHOLD,
+  hasTooltip = true,
+  isTimezoneShown = false,
+  isLive = false,
+  type = 'supporting',
+  size,
+  color = 'secondary',
+  weight,
+  xstyle,
+  className,
+  style,
+  ref,
+  'data-testid': testId,
+}: TimestampProps) {
+  const timeRef = useRef<HTMLTimeElement>(null);
+  const [now, setNow] = useState(() => new Date());
+
+  const date = parseValue(value);
+  const isoString = date.toISOString();
+
+  // Determine effective format
+  const diffSeconds = Math.round((now.getTime() - date.getTime()) / 1000);
+  const effectiveFormat: TimestampFormat =
+    format === 'auto'
+      ? Math.abs(diffSeconds) <= autoThreshold
+        ? 'relative'
+        : 'date_time'
+      : format;
+
+  // Format the display text
+  const displayText =
+    effectiveFormat === 'relative'
+      ? getRelativeTimeString(date, now)
+      : isAbsoluteFormat(effectiveFormat)
+        ? formatTimestamp(date, effectiveFormat, isTimezoneShown)
+        : '';
+
+  // Full absolute text for tooltip and aria-label
+  const fullAbsoluteText = getFullAbsoluteString(date);
+
+  // Live updates
+  useEffect(() => {
+    if (!isLive || effectiveFormat !== 'relative') {
+      return;
+    }
+
+    const interval = getLiveInterval(diffSeconds);
+    const timer = setInterval(() => {
+      setNow(new Date());
+    }, interval);
+
+    return () => clearInterval(timer);
+  }, [isLive, effectiveFormat, diffSeconds]);
+
+  const showTooltip = hasTooltip && effectiveFormat === 'relative';
+
+  const timestampProps = mergeProps(
+    themeProps('timestamp', {format: effectiveFormat}),
+    {className, style},
+  );
+
+  const timeElement = (
+    <Text
+      type={type}
+      size={size}
+      color={color}
+      weight={weight}
+      xstyle={xstyle}
+      {...timestampProps}>
+      <time
+        ref={mergeRefs(ref, timeRef)}
+        dateTime={isoString}
+        aria-label={
+          effectiveFormat === 'relative' ? fullAbsoluteText : undefined
+        }
+        data-testid={testId}
+        {...stylex.props(styles.time)}>
+        {displayText}
+      </time>
+    </Text>
+  );
+
+  if (showTooltip) {
+    return (
+      <>
+        {timeElement}
+        <Suspense fallback={null}>
+          <LazyXDSTooltip
+            anchorRef={timeRef}
+            content={fullAbsoluteText}
+            placement="above"
+          />
+        </Suspense>
+      </>
+    );
+  }
+
+  return timeElement;
+}
+
+Timestamp.displayName = 'Timestamp';

package/src/Timestamp/index.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file index.ts
+ * @input Timestamp component
+ * @output Exports all Timestamp module public API
+ * @position Entry point for Timestamp module
+ *
+ * SYNC: When adding new Timestamp files, update exports here
+ */
+
+export {Timestamp} from './Timestamp';
+export type {TimestampProps, TimestampFormat} from './Timestamp';

package/src/Toast/Toast.doc.mjs

@@ -0,0 +1,154 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'Toast',
+  displayName: 'Toast',
+  group: 'Toast',
+  category: 'Overlay',
+  hiddenComponents: ['ToastViewport'],
+  keywords: ["toast","notification","snackbar","alert","message","feedback","status"],
+
+  props: [
+    {
+      name: 'body',
+      type: 'ReactNode',
+      description: 'Primary message content.',
+      required: true,
+      slotElements: [{__element: 'Text', props: {type: 'body'}, children: 'Toast message'}],
+    },
+    {
+      name: 'type',
+      type: "'info' | 'error'",
+      description: 'Toast type controlling background color. Error toasts persist until dismissed.',
+      default: "'info'",
+    },
+    {
+      name: 'isAutoHide',
+      type: 'boolean',
+      description: 'Whether the toast auto-dismisses. Defaults to true for info, false for error.',
+    },
+    {
+      name: 'autoHideDuration',
+      type: 'number',
+      description: 'Duration in ms before auto-dismiss.',
+      default: '5000',
+    },
+    {
+      name: 'endContent',
+      type: 'ReactNode',
+      description: 'Content rendered at the trailing end (e.g. Undo button, link).',
+      slotElements: [
+        {__element: 'Icon', props: {icon: 'chevronDown', size: 'sm'}},
+        {__element: 'Badge', props: {label: '3'}},
+      ],
+    },
+    {
+      name: 'uniqueID',
+      type: 'string',
+      description: 'Unique identifier for deduplication.',
+    },
+    {
+      name: 'collisionBehavior',
+      type: "'overwrite' | 'ignore'",
+      description: 'Behavior when a toast with matching uniqueID already exists.',
+      default: "'overwrite'",
+    },
+    {
+      name: 'onHide',
+      type: '(reason: "auto" | "manual") => void',
+      description: 'Callback fired when the toast is removed.',
+    },
+  ],  theming: {
+    targets: [
+      {className: 'astryx-toast', visualProps: ['type']},
+    ],
+  },
+
+  usage: {
+    description:
+      'Toast shows a brief, non-blocking notification to confirm an action or present temporary information. Use it for scenarios where the user needs feedback but not a decision, such as saving, deleting, or changing a status.\n\nFor production use, prefer the `useToast()` hook; it handles positioning, stacking, auto-dismiss, and deduplication via `ToastViewport`. The `Toast` component renders the visual toast element inline and is useful for previews, documentation, and static showcases where the viewport lifecycle is not needed.',
+    bestPractices: [
+      {guidance: true, description: 'Keep messages short: only a few words that tell the user what happened, like "Changes saved" or "Message sent".'},
+      {guidance: true, description: 'Add an undo action in the endContent slot for reversible operations like deleting an item, so the user can recover without navigating away.'},
+      {guidance: true, description: 'Use uniqueID to deduplicate toasts that fire from repeated actions, like clicking a save button multiple times.'},
+      {guidance: true, description: 'Use error type for failures that need attention but not immediate action; it persists until dismissed so the user won\'t miss it.'},
+      {guidance: false, description: 'Don\'t use a toast for critical errors that block the user. Use Banner for persistent, in-context messaging that requires acknowledgment.'},
+      {guidance: false, description: 'Don\'t put long or multi-line content in a toast; it disappears after 5 seconds and the user may not finish reading.'},
+      {guidance: false, description: 'Don\'t show form validation errors as toasts. Use inline field validation so the user can see exactly which field needs fixing.'},
+    ],
+    anatomy: [
+      {name: 'Body', required: true, description: 'The primary message text describing what happened or what the user should know.'},
+      {name: 'End content', required: false, description: 'A trailing action like an Undo button or a link, placed after the body text.'},
+      {name: 'Dismiss button', required: true, description: 'A close button that lets the user manually dismiss the toast before auto-hide.'},
+    ],
+  },
+};
+
+// -------------------------------------------------------
+// Auto-generated translations below. Do not edit manually.
+// Regenerate with the dense compression protocol.
+// See .context/decisions/dense-compression-protocol.md
+// -------------------------------------------------------
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsZh = {
+  propDescriptions: {
+    body: '主要消息内容。',
+    type: 'Toast 类型，控制背景颜色。error toast 持续显示直到关闭。',
+    isAutoHide: '是否自动关闭。info 默认为 true，error 默认为 false。',
+    autoHideDuration: '自动关闭前的持续时间（毫秒）。',
+    endContent: '尾部渲染的内容（如撤销按钮、链接）。',
+    uniqueID: '用于去重的唯一标识符。',
+    collisionBehavior: '当已存在相同 uniqueID 的 toast 时的行为。',
+    onHide: '当 toast 被移除时触发的回调。',
+  },
+  usage: {
+    description:
+      'Toast 显示简短的非阻塞通知，用于确认操作或呈现临时信息。适用于用户需要反馈但不需要做决定的场景，如保存、删除或状态变更。\n\n生产环境中推荐使用 `useToast()` hook，它通过 `ToastViewport` 处理定位、堆叠、自动关闭和去重。`Toast` 组件以内联方式渲染 toast 视觉元素，适用于预览、文档和静态展示。',
+    bestPractices: [
+      {guidance: true, description: '保持消息简短，只需几个词告诉用户发生了什么，如"更改已保存"或"消息已发送"。'},
+      {guidance: true, description: '在 endContent 插槽中添加撤销操作，用于可逆操作如删除项目，让用户无需导航即可恢复。'},
+      {guidance: true, description: '使用 uniqueID 去重重复操作触发的 toast，如多次点击保存按钮。'},
+      {guidance: true, description: '对需要关注但不需要立即操作的错误使用 error 类型，它会持续显示直到关闭。'},
+      {guidance: false, description: '不要对阻塞用户的严重错误使用 toast，使用 Banner 进行持久的上下文消息传递。'},
+      {guidance: false, description: '不要在 toast 中放置长内容或多行内容，它会在5秒后消失，用户可能来不及阅读。'},
+      {guidance: false, description: '不要将表单验证错误显示为 toast，使用内联字段验证让用户看到具体哪个字段需要修复。'},
+    ],
+    anatomy: [
+      {name: '正文', required: true, description: '描述发生了什么或用户应该知道什么的主要消息文本。'},
+      {name: '尾部内容', required: false, description: '正文后的尾随操作，如撤销按钮或链接。'},
+      {name: '关闭按钮', required: true, description: '让用户在自动隐藏前手动关闭 toast 的关闭按钮。'},
+    ],
+  },
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+  description:
+    'toast notification w/ auto-dismiss, stacking, dedup, smooth animations; MediaTheme inverted surface',
+  usage: {
+    description:
+      'Brief non-blocking notification for action confirmations and temporary info. Use where user needs feedback not decisions: saves, deletes, status changes. useToast() hook for production (positioning, stacking, auto-dismiss, dedup via ToastViewport). Toast renders inline for previews/docs/static showcases.',
+    bestPractices: [
+      {guidance: true, description: 'Short messages, a few words: "Changes saved", "Message sent".'},
+      {guidance: true, description: 'Undo action in endContent for reversible ops like deletes.'},
+      {guidance: true, description: 'uniqueID to dedup repeated action toasts.'},
+      {guidance: true, description: 'Error type for failures needing attention; persists until dismissed.'},
+      {guidance: false, description: 'Don\'t use for critical blocking errors. Use Banner for persistent in-context messaging.'},
+      {guidance: false, description: 'Don\'t put long/multi-line content; disappears in 5s, user may not finish reading.'},
+      {guidance: false, description: 'Don\'t show form validation errors. Use inline field validation instead.'},
+    ],
+  },
+  propDescriptions: {
+    body: 'primary message content',
+    type: 'toast type; controls bg color; error persists until dismissed',
+    isAutoHide: 'auto-dismiss; true for info, false for error',
+    autoHideDuration: 'ms before auto-dismiss',
+    endContent: 'trailing end content (undo btn, link)',
+    uniqueID: 'unique id for dedup',
+    collisionBehavior: 'behavior when matching uniqueID exists',
+    onHide: 'callback when toast removed',
+  },
+};