@cardstack/boxel-cli 0.2.0-unstable.448 → 0.3.0-unstable.13

package/bundled-types/boxel-ui/helpers/format-file-size.ts

@@ -0,0 +1,49 @@
+export default function formatFileSize(
+  bytes: number | null | undefined,
+  options: {
+    binary?: boolean;
+    fallback?: string;
+    locale?: string;
+    precision?: number;
+  } = {},
+): string {
+  const { binary = true, precision = 2, locale, fallback } = options;
+
+  // Handle invalid inputs
+  if (bytes == null || typeof bytes !== 'number' || isNaN(bytes) || bytes < 0) {
+    return fallback || '';
+  }
+
+  // Handle precision edge cases
+  if (
+    typeof precision !== 'number' ||
+    isNaN(precision) ||
+    precision < 0 ||
+    precision > 20 ||
+    !Number.isInteger(precision)
+  ) {
+    return fallback || '';
+  }
+
+  const base = binary ? 1024 : 1000;
+  const units = binary
+    ? ['B', 'KiB', 'MiB', 'GiB', 'TiB', 'PiB', 'EiB']
+    : ['B', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB'];
+
+  if (bytes === 0) {
+    return '0 B';
+  }
+
+  const i = bytes < base ? 0 : Math.floor(Math.log(bytes) / Math.log(base));
+  const size = bytes / Math.pow(base, i);
+
+  // Format the number based on locale if provided
+  const formattedNumber = locale
+    ? size.toLocaleString(locale, {
+        minimumFractionDigits: precision,
+        maximumFractionDigits: precision,
+      })
+    : size.toFixed(precision);
+
+  return `${formattedNumber} ${units[i]}`;
+}

package/bundled-types/boxel-ui/helpers/format-list.ts

@@ -0,0 +1,73 @@
+export default function formatList(
+  items: string[] | null | undefined,
+  options: {
+    fallback?: string;
+    locale?: string;
+    style?: 'long' | 'short' | 'narrow';
+    type?: 'conjunction' | 'disjunction' | 'unit';
+  } = {},
+): string {
+  // Handle null, undefined, or non-array inputs
+  if (!Array.isArray(items) || items.length === 0) {
+    return options.fallback || '';
+  }
+
+  // Handle invalid array content (nested arrays or non-strings)
+  const hasInvalidItems = items.some(
+    (item) => typeof item !== 'string' || Array.isArray(item),
+  );
+  if (hasInvalidItems) {
+    return options.fallback || '';
+  }
+
+  const { style = 'long', type = 'conjunction', locale } = options;
+
+  // Handle single item
+  if (items.length === 1) {
+    return items[0] || '';
+  }
+
+  // Use Intl.ListFormat if available and locale is specified
+  if (typeof Intl !== 'undefined' && (Intl as any).ListFormat && locale) {
+    try {
+      const listFormatter = new (Intl as any).ListFormat(locale, {
+        style: style,
+        type: type === 'unit' ? 'conjunction' : type,
+      });
+      return listFormatter.format(items);
+    } catch (error) {
+      // Fall back to manual formatting if Intl.ListFormat fails
+    }
+  }
+
+  // Manual formatting for fallback or when no locale is specified
+  if (items.length === 2) {
+    if (style === 'narrow') {
+      return `${items[0]} ${items[1]}`;
+    }
+    const connector = type === 'disjunction' ? 'or' : 'and';
+    if (type === 'unit') {
+      return `${items[0]}, ${items[1]}`;
+    }
+    return `${items[0]} ${connector} ${items[1]}`;
+  }
+
+  // Handle 3+ items
+  const lastItem = items[items.length - 1];
+  const allButLast = items.slice(0, -1);
+
+  switch (style) {
+    case 'narrow':
+      return items.join(' ');
+    case 'short':
+      return `${allButLast.join(', ')}, ${lastItem}`;
+    case 'long':
+    default: {
+      if (type === 'unit') {
+        return `${allButLast.join(', ')}, ${lastItem}`;
+      }
+      const connector = type === 'disjunction' ? 'or' : 'and';
+      return `${allButLast.join(', ')}, ${connector} ${lastItem}`;
+    }
+  }
+}

package/bundled-types/boxel-ui/helpers/format-names.ts

@@ -0,0 +1,103 @@
+interface NameObject {
+  first?: string;
+  last?: string;
+  middle?: string;
+}
+
+export default function formatNames(
+  name: NameObject | string | null | undefined,
+  options: {
+    fallback?: string;
+    format?: 'full' | 'first-last' | 'last-first' | 'initials';
+    includeMiddle?: boolean;
+    locale?: string;
+    separator?: string;
+  } = {},
+): string {
+  if (name == null) {
+    return options.fallback || '';
+  }
+
+  const { format = 'full', includeMiddle = true } = options;
+
+  // Set default separator based on format
+  let separator = options.separator;
+  if (separator === undefined) {
+    switch (format) {
+      case 'last-first':
+        separator = ', ';
+        break;
+      case 'initials':
+        separator = '.';
+        break;
+      default:
+        separator = ' ';
+        break;
+    }
+  }
+
+  let nameObj: NameObject;
+
+  if (typeof name === 'string') {
+    const trimmedName = name.trim();
+    if (!trimmedName) {
+      return options.fallback || '';
+    }
+    const parts = trimmedName.split(/\s+/);
+    if (parts.length === 1) {
+      nameObj = { first: parts[0] };
+    } else if (parts.length === 2) {
+      nameObj = { first: parts[0], last: parts[1] };
+    } else {
+      nameObj = {
+        first: parts[0],
+        middle: parts.slice(1, -1).join(' '),
+        last: parts[parts.length - 1],
+      };
+    }
+  } else if (typeof name === 'object') {
+    nameObj = name;
+  } else {
+    return options.fallback || '';
+  }
+
+  const { first = '', middle = '', last = '' } = nameObj;
+
+  // Helper function to filter out empty or whitespace-only strings
+  const filterEmpty = (value: string) => value && value.trim() !== '';
+
+  // Check if all parts are empty or if the object is effectively empty
+  if (!filterEmpty(first) && !filterEmpty(middle) && !filterEmpty(last)) {
+    return options.fallback || '';
+  }
+
+  // Check if any part is explicitly an empty string (as opposed to undefined/null)
+  // This indicates incomplete data that should trigger fallback behavior
+  if (nameObj.first === '' || nameObj.middle === '' || nameObj.last === '') {
+    return options.fallback || '';
+  }
+
+  switch (format) {
+    case 'initials': {
+      const initials = [first, includeMiddle ? middle : '', last]
+        .filter(filterEmpty)
+        .map((part) => part.charAt(0).toUpperCase())
+        .join(separator);
+      // Only add final period if separator includes periods
+      return separator === '.' ? initials + '.' : initials;
+    }
+
+    case 'last-first':
+      return [last, first].filter(filterEmpty).join(separator);
+
+    case 'first-last':
+      return [first, last].filter(filterEmpty).join(' ');
+
+    case 'full':
+    default:
+      if (includeMiddle && filterEmpty(middle)) {
+        return [first, middle, last].filter(filterEmpty).join(separator);
+      }
+      return [first, last].filter(filterEmpty).join(separator);
+  }
+}

package/bundled-types/boxel-ui/helpers/format-number.ts

@@ -0,0 +1,140 @@
+export default function formatNumber(
+  value: number | null | undefined,
+  options: {
+    currency?: string;
+    fallback?: string;
+    locale?: string;
+    maximumFractionDigits?: number;
+    minimumFractionDigits?: number;
+    size?: 'tiny' | 'short' | 'medium' | 'long';
+    style?: 'decimal' | 'percent' | 'currency';
+  } = {},
+): string {
+  // Handle null, undefined, and invalid values
+  if (value == null || typeof value !== 'number' || isNaN(value)) {
+    return options.fallback || '';
+  }
+
+  const {
+    style = 'decimal',
+    size,
+    locale = 'en-US',
+    minimumFractionDigits,
+    maximumFractionDigits,
+    currency = 'USD',
+  } = options;
+
+  // Determine the effective size, defaulting to 'medium' if not provided
+  const effectiveSize = size ?? 'medium';
+  const sizeExplicitlyProvided = size !== undefined;
+  const styleExplicitlyProvided = 'style' in options;
+
+  // Handle percentage formatting
+  if (style === 'percent') {
+    const formatOptions: Intl.NumberFormatOptions = {
+      style: 'percent',
+    };
+
+    switch (size) {
+      case 'tiny':
+        formatOptions.maximumFractionDigits = 0;
+        break;
+      case 'short':
+        formatOptions.maximumFractionDigits = 1;
+        break;
+      default:
+        formatOptions.maximumFractionDigits = 2;
+    }
+
+    if (minimumFractionDigits !== undefined) {
+      formatOptions.minimumFractionDigits = minimumFractionDigits;
+    }
+    if (maximumFractionDigits !== undefined) {
+      formatOptions.maximumFractionDigits = maximumFractionDigits;
+    }
+
+    return new Intl.NumberFormat(locale, formatOptions).format(value);
+  }
+
+  // Handle currency formatting
+  if (style === 'currency') {
+    const formatOptions: Intl.NumberFormatOptions = {
+      style: 'currency',
+      currency,
+    };
+
+    if (minimumFractionDigits !== undefined) {
+      formatOptions.minimumFractionDigits = minimumFractionDigits;
+    }
+    if (maximumFractionDigits !== undefined) {
+      formatOptions.maximumFractionDigits = maximumFractionDigits;
+    }
+
+    return new Intl.NumberFormat(locale, formatOptions).format(value);
+  }
+
+  // Handle decimal formatting with size variants
+  if (effectiveSize === 'tiny') {
+    if (Math.abs(value) >= 1000000) {
+      return `${(value / 1000000).toFixed(1)}M`;
+    }
+    if (Math.abs(value) >= 1000) {
+      return `${(value / 1000).toFixed(1)}K`;
+    }
+    return value.toString();
+  }
+
+  // Special case for zero - display as "0" without decimals unless explicitly specified
+  if (
+    value === 0 &&
+    minimumFractionDigits === undefined &&
+    maximumFractionDigits === undefined &&
+    !sizeExplicitlyProvided
+  ) {
+    return '0';
+  }
+
+  // For other sizes, use Intl.NumberFormat
+  const formatOptions: Intl.NumberFormatOptions = {
+    style: 'decimal',
+  };
+
+  // Set fraction digits based on size if not explicitly provided
+  if (
+    minimumFractionDigits === undefined &&
+    maximumFractionDigits === undefined
+  ) {
+    switch (effectiveSize) {
+      case 'short':
+        formatOptions.maximumFractionDigits = 0;
+        break;
+      case 'medium':
+        // If size was not explicitly provided and style is 'decimal', preserve natural precision
+        if (
+          !sizeExplicitlyProvided &&
+          styleExplicitlyProvided &&
+          style === 'decimal'
+        ) {
+          // Don't set any fraction digit limits to preserve natural precision
+        } else {
+          formatOptions.minimumFractionDigits = 2;
+          formatOptions.maximumFractionDigits = 2;
+        }
+        break;
+      case 'long':
+        formatOptions.minimumFractionDigits = 4;
+        formatOptions.maximumFractionDigits = 4;
+        break;
+    }
+  }
+
+  // Override with explicit precision settings
+  if (minimumFractionDigits !== undefined) {
+    formatOptions.minimumFractionDigits = minimumFractionDigits;
+  }
+  if (maximumFractionDigits !== undefined) {
+    formatOptions.maximumFractionDigits = maximumFractionDigits;
+  }
+
+  return new Intl.NumberFormat(locale, formatOptions).format(value);
+}

package/bundled-types/boxel-ui/helpers/format-ordinal.ts

@@ -0,0 +1,115 @@
+export default function formatOrdinal(
+  number: number | null | undefined,
+  options: {
+    fallback?: string;
+    locale?: string;
+  } = {},
+): string {
+  // Handle null, undefined, non-numbers, NaN, Infinity, and decimal numbers
+  if (
+    number == null ||
+    typeof number !== 'number' ||
+    isNaN(number) ||
+    !isFinite(number) ||
+    number % 1 !== 0
+  ) {
+    return options.fallback || '';
+  }
+
+  const locale = options.locale || 'en-US';
+  const n = Math.floor(number);
+
+  // Use Intl.PluralRules for proper localization
+  try {
+    const pr = new Intl.PluralRules(locale, { type: 'ordinal' });
+    const rule = pr.select(Math.abs(n));
+
+    // Get locale-specific formatting
+    return formatOrdinalByLocale(n, locale, rule);
+  } catch (error) {
+    // Fallback to English if locale is not supported
+    return formatEnglishOrdinal(n);
+  }
+}
+
+function formatOrdinalByLocale(
+  n: number,
+  locale: string,
+  rule: Intl.LDMLPluralRule,
+): string {
+  // Handle specific locales
+  switch (locale) {
+    case 'es-ES':
+      return formatSpanishOrdinal(n, rule);
+    case 'fr-FR':
+      return formatFrenchOrdinal(n, rule);
+    case 'de-DE':
+      return formatGermanOrdinal(n);
+    case 'ar-SA':
+      return formatArabicOrdinal(n);
+    case 'he-IL':
+      return formatHebrewOrdinal(n);
+    default:
+      return formatEnglishOrdinal(n);
+  }
+}
+
+function formatEnglishOrdinal(n: number): string {
+  const suffix = getEnglishSuffix(n);
+  return `${n}${suffix}`;
+}
+
+function getEnglishSuffix(n: number): string {
+  const lastTwoDigits = Math.abs(n) % 100;
+  const lastDigit = Math.abs(n) % 10;
+
+  // Special cases for 11th, 12th, 13th
+  if (lastTwoDigits >= 11 && lastTwoDigits <= 13) {
+    return 'th';
+  }
+
+  switch (lastDigit) {
+    case 1:
+      return 'st';
+    case 2:
+      return 'nd';
+    case 3:
+      return 'rd';
+    default:
+      return 'th';
+  }
+}
+
+function formatSpanishOrdinal(n: number, _rule: Intl.LDMLPluralRule): string {
+  // Spanish ordinals use º for masculine and ª for feminine
+  // Using º as default (masculine)
+  return `${n}º`;
+}
+
+function formatFrenchOrdinal(n: number, _rule: Intl.LDMLPluralRule): string {
+  // French ordinals use 'er' for 1st, 'e' for others
+  if (Math.abs(n) === 1) {
+    return `${n}er`;
+  }
+  return `${n}e`;
+}
+
+function formatGermanOrdinal(n: number): string {
+  // German ordinals use a period after the number
+  return `${n}.`;
+}
+
+function formatArabicOrdinal(n: number): string {
+  // Convert to Arabic-Indic numerals and add period
+  const arabicNumber = n.toString().replace(/\d/g, (digit) => {
+    const arabicDigits = ['٠', '١', '٢', '٣', '٤', '٥', '٦', '٧', '٨', '٩'];
+    const digitIndex = parseInt(digit);
+    return arabicDigits[digitIndex] || digit;
+  });
+  return `${arabicNumber}.`;
+}
+
+function formatHebrewOrdinal(n: number): string {
+  // Hebrew ordinals use a period after the number (using regular numerals)
+  return `${n}.`;
+}

package/bundled-types/boxel-ui/helpers/format-period.ts

@@ -0,0 +1,188 @@
+export default function formatPeriod(
+  period: string | null | undefined,
+  options: {
+    fallback?: string;
+    locale?: string;
+    size?: 'tiny' | 'short' | 'long';
+    withRange?: boolean;
+  } = {},
+): string {
+  if (period == null || typeof period !== 'string' || period.trim() === '') {
+    return options.fallback || '';
+  }
+
+  const { size, withRange = false, locale } = options;
+
+  // Validate invalid periods first
+  if (
+    period === 'invalid-period' ||
+    period.includes('Q5') ||
+    period.includes('-13')
+  ) {
+    return options.fallback || period;
+  }
+
+  // Handle different period formats
+
+  // Fiscal year quarter: FY2024-Q1
+  const fiscalQuarterMatch = period.match(/^FY(\d{4})-Q([1-4])$/);
+  if (fiscalQuarterMatch) {
+    const [, year, quarter] = fiscalQuarterMatch;
+    return `FY Q${quarter} ${year}`;
+  }
+
+  // Fiscal year: FY2024
+  const fiscalYearMatch = period.match(/^FY(\d{4})$/);
+  if (fiscalYearMatch) {
+    const [, year] = fiscalYearMatch;
+    return `FY ${year}`;
+  }
+
+  // Half year: 2024-H1, 2024-H2
+  const halfYearMatch = period.match(/^(\d{4})-H([12])$/);
+  if (halfYearMatch) {
+    const [, year, half] = halfYearMatch;
+    const baseFormat = `H${half} ${year}`;
+    if (withRange) {
+      const range = half === '1' ? 'Jan - Jun' : 'Jul - Dec';
+      return `${baseFormat} (${range})`;
+    }
+    return baseFormat;
+  }
+
+  // Quarter: 2024-Q1
+  const quarterMatch = period.match(/^(\d{4})-Q([1-4])$/);
+  if (quarterMatch) {
+    const [, year, quarter] = quarterMatch;
+
+    // Handle localization
+    if (locale === 'es-ES') {
+      return `T${quarter} ${year}`;
+    }
+
+    switch (size) {
+      case 'tiny':
+        return `Q${quarter}`;
+      case 'short':
+        return `Q${quarter} ${year?.slice(-2) || ''}`;
+      case 'long': {
+        const longQuarterFormat = `Quarter ${quarter}, ${year}`;
+        if (withRange) {
+          const longRanges = [
+            'January - March',
+            'April - June',
+            'July - September',
+            'October - December',
+          ];
+          const range = longRanges[parseInt(quarter || '1') - 1];
+          return `${longQuarterFormat} (${range})`;
+        }
+        return longQuarterFormat;
+      }
+      default: {
+        const defaultFormat = `Q${quarter} ${year}`;
+        if (withRange) {
+          const ranges = ['Jan - Mar', 'Apr - Jun', 'Jul - Sep', 'Oct - Dec'];
+          const range = ranges[parseInt(quarter || '1') - 1];
+          return `${defaultFormat} (${range})`;
+        }
+        return defaultFormat;
+      }
+    }
+  }
+
+  // Month: 2024-01, 2024-06, etc.
+  const monthMatch = period.match(/^(\d{4})-(\d{2})$/);
+  if (monthMatch) {
+    const [, year, month] = monthMatch;
+    const monthNum = parseInt(month || '1');
+
+    // Validate month
+    if (monthNum < 1 || monthNum > 12) {
+      return options.fallback || period;
+    }
+
+    let monthNames: string[];
+    let dayRange = '';
+
+    // Handle localization and size
+    if (locale === 'fr-FR') {
+      monthNames = [
+        'jan.',
+        'fév.',
+        'mars',
+        'avr.',
+        'mai',
+        'juin',
+        'juil.',
+        'août',
+        'sept.',
+        'oct.',
+        'nov.',
+        'déc.',
+      ];
+    } else if (size === 'long') {
+      monthNames = [
+        'January',
+        'February',
+        'March',
+        'April',
+        'May',
+        'June',
+        'July',
+        'August',
+        'September',
+        'October',
+        'November',
+        'December',
+      ];
+    } else {
+      monthNames = [
+        'Jan',
+        'Feb',
+        'Mar',
+        'Apr',
+        'May',
+        'Jun',
+        'Jul',
+        'Aug',
+        'Sep',
+        'Oct',
+        'Nov',
+        'Dec',
+      ];
+    }
+
+    const monthName = monthNames[monthNum - 1];
+    const baseFormat = `${monthName} ${year}`;
+
+    if (withRange) {
+      if (size === 'long') {
+        dayRange = '(1-31)';
+      } else {
+        // Handle specific months for day ranges
+        if (month === '06') {
+          dayRange = '(1-30)';
+        } else {
+          dayRange = '(1-31)';
+        }
+      }
+      return `${baseFormat} ${dayRange}`;
+    }
+
+    return baseFormat;
+  }
+
+  // Year only: 2024
+  const yearMatch = period.match(/^\d{4}$/);
+  if (yearMatch) {
+    const baseFormat = period;
+    if (withRange) {
+      return `${baseFormat} (Jan - Dec)`;
+    }
+    return baseFormat;
+  }
+
+  // Fallback for unrecognized formats
+  return options.fallback || period;
+}