Utility Functions

/**
 * Returns the next color from the ordered colors array using modulo cycling
 * @param index - Index to get color for (will wrap around using modulo)
 * @returns Color key from the theme colors object
 */
function get_next_color(index: number): keyof typeof colors;

import { get_next_color } from "@gradio/utils";

// Get colors for multiple items with automatic cycling
const items = ["Item 1", "Item 2", "Item 3", "Item 4", "Item 5"];

items.forEach((item, index) => {
  const color = get_next_color(index);
  console.log(`${item} gets color: ${color}`);
});

// Cycling continues automatically
const color10 = get_next_color(10);  // Wraps around to beginning
const color0 = get_next_color(0);    // Same as index 0

// Use in chart or visualization
function createChart(data: Array<{ label: string; value: number }>) {
  return data.map((item, index) => ({
    ...item,
    color: get_next_color(index)
  }));
}

/**
 * Formats seconds into HH:MM:SS or MM:SS time string
 * @param seconds - Time duration in seconds
 * @returns Formatted time string (HH:MM:SS if hours > 0, otherwise MM:SS)
 */
function format_time(seconds: number): string;

import { format_time } from "@gradio/utils";

// Various time formats
console.log(format_time(30));     // "0:30"
console.log(format_time(90));     // "1:30"
console.log(format_time(3600));   // "1:00:00"
console.log(format_time(3665));   // "1:01:05"
console.log(format_time(7294));   // "2:01:34"

// Use in media players
function updateTimeDisplay(currentTime: number, totalTime: number) {
  const current = format_time(currentTime);
  const total = format_time(totalTime);
  document.getElementById("time-display")!.textContent = `${current} / ${total}`;
}

// Use in progress indicators
function formatProgress(elapsedSeconds: number) {
  return `Elapsed: ${format_time(elapsedSeconds)}`;
}

/**
 * Converts numeric values to CSS pixel units or passes through string values
 * @param dimension_value - Value to convert (number or string)
 * @returns String with "px" suffix for numbers, or original string
 */
function css_units(dimension_value: string | number): string;

import { css_units } from "@gradio/utils";

// Number to pixel units
console.log(css_units(100));        // "100px"
console.log(css_units(0));          // "0px"
console.log(css_units(-50));        // "-50px"

// String values pass through unchanged
console.log(css_units("50%"));      // "50%"
console.log(css_units("10em"));     // "10em"
console.log(css_units("auto"));     // "auto"

// Use in dynamic styling
function applyDimensions(element: HTMLElement, width: string | number, height: string | number) {
  element.style.width = css_units(width);
  element.style.height = css_units(height);
}

// Component styling helper
interface ComponentStyle {
  width?: string | number;
  height?: string | number;
  margin?: string | number;
  padding?: string | number;
}

function createStyleObject(styles: ComponentStyle): CSSStyleDeclaration {
  const result: any = {};
  
  if (styles.width !== undefined) result.width = css_units(styles.width);
  if (styles.height !== undefined) result.height = css_units(styles.height);
  if (styles.margin !== undefined) result.margin = css_units(styles.margin);
  if (styles.padding !== undefined) result.padding = css_units(styles.padding);
  
  return result;
}

/**
 * Svelte action for handling copy-to-clipboard functionality
 * @param node - HTML div element to attach the copy behavior to
 * @returns ActionReturn object with destroy method for cleanup
 */
function copy(node: HTMLDivElement): ActionReturn;

// Svelte component usage
<script>
  import { copy } from "@gradio/utils";
</script>

<!-- Basic usage with copy button -->
<div use:copy>
  <button class="copy_code_button">
    <span>Copy</span>
    <div style="opacity: 0;">Copied!</div>
  </button>
  <pre>const message = "Hello, world!";</pre>
</div>

<!-- Code block with copy functionality -->
<div use:copy class="code-container">
  <button class="copy_code_button">
    <svg><!-- copy icon --></svg>
    <div class="success-indicator">✓</div>
  </button>
  <code>
    npm install @gradio/utils
  </code>
</div>

<!-- Multiple code blocks -->
<div use:copy>
  <div class="code-block">
    <button class="copy_code_button">Copy</button>
    <pre>console.log("First block");</pre>
  </div>
  
  <div class="code-block">
    <button class="copy_code_button">Copy</button>
    <pre>console.log("Second block");</pre>
  </div>
</div>

// Modern browsers (preferred)
if ("clipboard" in navigator) {
  await navigator.clipboard.writeText(value);
}

// Fallback for older browsers
else {
  const textArea = document.createElement("textarea");
  textArea.value = value;
  document.body.prepend(textArea);
  textArea.select();
  document.execCommand("copy");
  textArea.remove();
}