{
  "tag": "ed-format-date",
  "kind": "component",
  "summary": "Shows a date or time in the user's locale from a raw date value, so every date reads the same way across the\nproduct.",
  "status": "experimental",
  "since": "1.0",
  "docs": "https://test-apps.eurodata.de/a/eurodata-ui/docs/components/format-date/",
  "usage": "https://test-apps.eurodata.de/a/eurodata-ui/docs/components/format-date/usage/",
  "playwright": "getByTestId('…')",
  "dependencies": [],
  "use": [
    "Every absolute date or time users see — created and modified stamps, due dates, booking periods, document metadata",
    "Absolute dates for values users reference, compare, or cite later — records, receipts, deadlines",
    "A birthday or entry date in an employee record, shown as a day without a time or time zone"
  ],
  "notFor": [
    {
      "when": "\"How long ago\" recency phrasing in feeds or logs",
      "instead": "[Relative Time](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/relative-time)"
    },
    {
      "when": "A date the user is supposed to edit",
      "instead": "an editable date control"
    }
  ],
  "rules": [
    {
      "id": "format-date/never-hand-format",
      "rule": "Never hand-format a date, and never assemble a date string by hand or from a hardcoded pattern — pass the raw date and let the component follow the user's locale.",
      "why": "\"24.07.2026\" hardcodes German day-month order — the same value must read \"7/24/2026\" for a US user. A string assembled by hand or from a hardcoded pattern breaks the moment the product meets another locale.",
      "check": "warning"
    },
    {
      "id": "format-date/iso-8601-value",
      "rule": "Pass ISO 8601 strings or Date objects, so the value is unambiguous.",
      "check": "error"
    },
    {
      "id": "format-date/date-only-for-days",
      "rule": "Pass a date-only string for a value that is a day rather than a moment — a due date, a birthday, a posting date.",
      "why": "Adding a fake `T00:00:00Z` to it makes the displayed day depend on the viewer's time zone.",
      "check": "warning"
    },
    {
      "id": "format-date/time-zone-for-moments",
      "rule": "Set a time zone only for values that name a moment.",
      "why": "A calendar day has no moment to convert, so the setting is ignored there and the day renders as written."
    },
    {
      "id": "format-date/only-needed-parts",
      "rule": "Show only the parts the task needs — a due date needs no seconds, and date plus hour and minute covers most timestamps. Never show seconds or the time-zone name unless they carry real meaning, such as audit trails or cross-zone scheduling.",
      "check": "warning"
    },
    {
      "id": "format-date/same-parts-per-kind",
      "rule": "Keep the same parts for the same kind of value across the product, so lists and columns stay scannable.",
      "check": "warning"
    },
    {
      "id": "format-date/hour-format-auto",
      "rule": "Leave the hour format on auto, so the locale decides between 12- and 24-hour time — never force 12- or 24-hour time on every user when the locale already chooses correctly.",
      "check": "warning"
    }
  ],
  "api": {
    "attributes": [
      {
        "name": "date",
        "property": "date",
        "type": "null | string | { toString: { }, toDateString: { }, toTimeString: { }, toLocaleString: { }, toLocaleDateString: { }, toLocaleTimeString: { }, valueOf: { }, getTime: { }, getFullYear: { }, getUTCFullYear: { }, getMonth: { }, getUTCMonth: { }, getDate: { }, getUTCDate: { }, getDay: { }, getUTCDay: { }, getHours: { }, getUTCHours: { }, getMinutes: { }, getUTCMinutes: { }, getSeconds: { }, getUTCSeconds: { }, getMilliseconds: { }, getUTCMilliseconds: { }, getTimezoneOffset: { }, setTime: { }, setMilliseconds: { }, setUTCMilliseconds: { }, setSeconds: { }, setUTCSeconds: { }, setMinutes: { }, setUTCMinutes: { }, setHours: { }, setUTCHours: { }, setDate: { }, setUTCDate: { }, setMonth: { }, setUTCMonth: { }, setFullYear: { }, setUTCFullYear: { }, toUTCString: { }, toISOString: { }, toJSON: { }, __@toPrimitive@537: { } }",
        "default": "new Date()",
        "description": "The date/time to format. If not set, the current date and time will be used. Set `null` or an empty value to\nrender nothing. A value that cannot be read renders nothing either, and says so in the console.\n\nWith no format options set, the output names what the value names — a month value shows a month, a year value a\nyear.\n\nA string is read as a **calendar day** when it carries no time of day (`2026-08-03`, `2026-08`, `2026`) and as an\n**exact instant** when it does (`2026-08-03T10:30:00Z`). A calendar day renders as the day it names in every time\nzone; an instant is expressed in the viewer's zone unless `time-zone` says otherwise. Use the ISO 8601 format either\nway — to serialize a `Date`, use\n[`date.toISOString()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)."
      },
      {
        "name": "weekday",
        "property": "weekday",
        "type": "'short' | 'long' | 'narrow' | undefined",
        "description": "The format for displaying the weekday."
      },
      {
        "name": "era",
        "property": "era",
        "type": "'short' | 'long' | 'narrow' | undefined",
        "description": "The format for displaying the era."
      },
      {
        "name": "year",
        "property": "year",
        "type": "'numeric' | '2-digit' | undefined",
        "description": "The format for displaying the year."
      },
      {
        "name": "month",
        "property": "month",
        "type": "'short' | 'long' | 'numeric' | '2-digit' | 'narrow' | undefined",
        "description": "The format for displaying the month."
      },
      {
        "name": "day",
        "property": "day",
        "type": "'numeric' | '2-digit' | undefined",
        "description": "The format for displaying the day."
      },
      {
        "name": "hour",
        "property": "hour",
        "type": "'numeric' | '2-digit' | undefined",
        "description": "The format for displaying the hour."
      },
      {
        "name": "minute",
        "property": "minute",
        "type": "'numeric' | '2-digit' | undefined",
        "description": "The format for displaying the minute."
      },
      {
        "name": "second",
        "property": "second",
        "type": "'numeric' | '2-digit' | undefined",
        "description": "The format for displaying the second."
      },
      {
        "name": "time-zone-name",
        "property": "timeZoneName",
        "type": "'short' | 'long' | 'shortOffset' | 'longOffset' | 'shortGeneric' | 'longGeneric' | undefined",
        "description": "How to name the time zone beside the time, if at all. Unset shows no zone name. The `Offset` and `Generic` forms\nare the ones ECMA-402 adds beyond a plain name: `GMT-4`, `GMT-04:00`, `ET`, `Eastern Time`."
      },
      {
        "name": "time-zone",
        "property": "timeZone",
        "type": "string | undefined",
        "description": "The time zone to express the time in. Only meaningful for a `date` that names an instant — a calendar day names no\ninstant to convert, so it is ignored there and the day renders as written."
      },
      {
        "name": "hour-format",
        "property": "hourFormat",
        "type": "'auto' | '12' | '24'",
        "default": "'auto'",
        "description": "Which clock the hour is read on. `auto` leaves that to the locale, which is what makes an\nunknown value behave like `auto` rather than like either explicit choice."
      },
      {
        "name": "dir",
        "property": "dir",
        "type": "string"
      },
      {
        "name": "lang",
        "property": "lang",
        "type": "string"
      }
    ],
    "properties": [],
    "methods": [],
    "events": [],
    "slots": [],
    "cssProperties": [],
    "parts": [],
    "states": []
  },
  "import": "import '@eurodata/eurodata-ui/dist/components/format-date/format-date.js';",
  "react": {
    "component": "EdFormatDate",
    "import": "import EdFormatDate from '@eurodata/eurodata-ui/dist/react/format-date/index.js';"
  }
}