@norconsult-digital-public/isypixel 2.0.2 → 2.0.4-canary.1

package/dist/docs/web-components/ip-date-display/llm.md

@@ -0,0 +1,161 @@
+# ip-date-display
+
+A presentational component that displays a date formatted for reading. It supports a selectable date detail level (`dateFormat`), optional time (`timeFormat`), and a `variant` that sets the text colour: three neutral emphasis levels or three semantic colours. An optional leading `icon` slot lets the consumer add an indicator. Use it for deadlines, completion dates, and other dates that should be emphasised by state.
+
+The component is purely presentational: it is not interactive, emits no events, and does not participate in forms. The `variant` is set by the consumer, not computed internally.
+
+The locale is read reactively from `PixelLocaleService`. There is no `locale` prop. Calling `PixelLocaleService.setLocale(...)` re-renders the date in the new locale automatically.
+
+**Storybook:** https://pixel.isy.no/storybook/?path=/docs/core-ui-ip-date-display-usage--docs
+
+> This component requires ISY Pixel global styles to render correctly. Always remind the user to verify that styles are imported in their global stylesheet. See `llm.md` in the package root for style import options.
+
+## Attributes
+
+| Attribute    | Type   | Default     | Values                                                                        | Description                                                                                                                                                                                                                            |
+| ------------ | ------ | ----------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `date`       | string | `""`        | ISO 8601 date or datetime                                                     | The date to display, e.g. `"2025-08-19"` or `"2025-08-19T14:30"`. Formatted internally. An empty value renders nothing; an unparseable value renders a localized "Invalid date" fallback.                                              |
+| `dateFormat` | string | `"short"`   | `"short"`, `"medium"`, `"long"`                                               | Date detail level. Maps to the `Intl.DateTimeFormat` `dateStyle` option.                                                                                                                                                               |
+| `timeFormat` | string | `"none"`    | `"none"`, `"short"`, `"medium"`                                               | Whether and how detailed the time is shown. Maps to `Intl.DateTimeFormat` `timeStyle`; `"none"` shows no time. Only applies when `date` has a time component.                                                                          |
+| `variant`    | string | `"primary"` | `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"error"` | Visual treatment. `primary`/`secondary`/`tertiary` are neutral emphasis levels; `success`/`warning`/`error` colour the date. The slotted icon inherits this colour. The semantic colour is generic: use `label` to convey its meaning. |
+| `label`      | string | `""`        | Any string                                                                    | Optional accessible label describing what a semantic variant means, e.g. `"Overdue"` or `"Do not start before"`. Rendered as visually hidden text.                                                                                     |
+
+## Slots
+
+| Slot   | Description                                                                                                              |
+| ------ | ------------------------------------------------------------------------------------------------------------------------ |
+| `icon` | Optional leading icon shown before the date. Decorative (`aria-hidden`); inherits the variant colour via `currentColor`. |
+
+## Events
+
+None. Purely presentational.
+
+## Formatting
+
+The date is formatted with `Intl.DateTimeFormat(PixelLocaleService.getLocale(), { dateStyle, timeStyle })`.
+
+| `dateFormat` / `timeFormat` | `nb-NO`                     | `en-US`                      |
+| --------------------------- | --------------------------- | ---------------------------- |
+| `short` / `none`            | `19.08.2025`                | `8/19/25`                    |
+| `short` / `short`           | `19.08.2025, 14:30`         | `8/19/25, 2:30 PM`           |
+| `long` / `short`            | `19. august 2025 kl. 14:30` | `August 19, 2025 at 2:30 PM` |
+
+- `timeFormat` only has an effect when `date` carries a time component (an ISO datetime such as `2025-08-19T14:30`). A date-only value ignores `timeFormat`.
+- Date-only values are formatted in UTC so a timezone-shifted midnight cannot move the displayed calendar day.
+- An empty `date` renders nothing. A non-empty but unparseable `date` renders a localized "Invalid date" fallback.
+
+## Accessibility
+
+- The date renders inside a `<time datetime="...">` element. The `datetime` attribute reflects the full ISO value passed in `date`, including the time when present.
+- A semantic variant's colour is generic and not conveyed to assistive tech on its own. Set `label` to describe what it means (e.g. "Overdue"); it is announced as visually hidden text. Without a `label`, a semantic colour carries no meaning for screen readers.
+- The slotted `icon` is decorative and marked `aria-hidden`. It reinforces the variant visually but carries no meaning for screen readers.
+- When `date` is unparseable, the fallback renders only the localized "Invalid date" text: neither the slotted `icon` nor a `label` is shown, since neither applies to an error state.
+
+## Localisation
+
+The visible "Invalid date" fallback ships in English and Norwegian (`nb-NO`) and is resolved through `PixelI18nService`, the same mechanism as other Pixel components. Override it with `PixelI18nService.setCustomLanguage({ 'ip-date-display': { ... } })`. The `label` is not localised by the component: the consumer supplies it in the correct language.
+
+| Key           | `en`         | `nb-NO`      |
+| ------------- | ------------ | ------------ |
+| `invalidDate` | Invalid date | Ugyldig dato |
+
+## Design tokens
+
+> The `success`, `warning`, and `error` variants use temporary non-adaptive primitive stand-ins. No contrast-approved semantic tokens for these exist in Figma yet, so suitable `extended/*` shades are used and marked `//TODO` in the SCSS. The final tokens and WCAG contrast are resolved in the post-summer design cleanup.
+
+| SCSS variable                             | Role                                            |
+| ----------------------------------------- | ----------------------------------------------- |
+| `$ip_color_text_primary_black`            | Text colour for `variant="primary"`             |
+| `$ip_color_text_secondary_default`        | Text colour for `variant="secondary"`           |
+| `$ip_color_text_tertiary_default`         | Text colour for `variant="tertiary"`            |
+| `$ip_color_extended_green-950`            | Text colour for `variant="success"` (temporary) |
+| `$ip_color_extended_yellow-950`           | Text colour for `variant="warning"` (temporary) |
+| `$ip_color_extended_red-600`              | Text colour for `variant="error"` (temporary)   |
+| `$ip_typography_body_font_family_default` | Date font family                                |
+| `$ip_typography_body_font_size_small`     | Date font size                                  |
+| `$ip_typography_body_font_weight_default` | Date font weight                                |
+| `$ip_spacing_space_100`                   | Gap between a slotted icon and the date         |
+
+## Usage
+
+### HTML
+
+```js
+import '@norconsult-digital-public/isypixel/web-components/ip-date-display.js';
+```
+
+```html
+<ip-date-display date="2025-08-19" date-format="long" variant="error" label="Overdue">
+  <i slot="icon" class="fas fa-triangle-exclamation"></i>
+</ip-date-display>
+```
+
+### React
+
+```tsx
+import { IpDateDisplay } from '@norconsult-digital-public/isypixel/web-components/react';
+
+<IpDateDisplay date='2025-08-19' dateFormat='long' variant='error' label='Overdue'>
+  <i slot='icon' className='fas fa-triangle-exclamation' />
+</IpDateDisplay>;
+```
+
+### Vue
+
+```vue
+<script setup lang="ts">
+import { IpDateDisplay } from '@norconsult-digital-public/isypixel/web-components/vue';
+</script>
+
+<template>
+  <IpDateDisplay date="2025-08-19" date-format="long" variant="error" label="Overdue">
+    <i slot="icon" class="fas fa-triangle-exclamation" />
+  </IpDateDisplay>
+</template>
+```
+
+### Angular
+
+```ts
+import { IpDateDisplay } from '@norconsult-digital-public/isypixel/web-components/angular';
+```
+
+```html
+<ip-date-display date="2025-08-19" date-format="long" variant="error" label="Overdue">
+  <i slot="icon" class="fas fa-triangle-exclamation"></i>
+</ip-date-display>
+```
+
+### Svelte
+
+```svelte
+<script lang="ts">
+  import '@norconsult-digital-public/isypixel/web-components/ip-date-display.js';
+</script>
+
+<ip-date-display date="2025-08-19" date-format="long" variant="error" label="Overdue">
+  <i slot="icon" class="fas fa-triangle-exclamation"></i>
+</ip-date-display>
+```
+
+### Blazor
+
+> Attribute names must be **kebab-case** in Blazor HTML.
+
+Copy `ip-date-display.js` to `wwwroot/lib/isypixel/components/` at build time. See `llm.md` in the package root for the MSBuild target.
+
+```html
+<script type="module" src="lib/isypixel/components/ip-date-display.js"></script>
+
+<ip-date-display date="2025-08-19" date-format="long" variant="error" label="Overdue">
+  <i slot="icon" class="fas fa-triangle-exclamation"></i>
+</ip-date-display>
+```
+
+### Set the locale
+
+```ts
+import { PixelLocaleService } from '@norconsult-digital-public/isypixel/web-components/services';
+
+PixelLocaleService.setLocale('nb-NO'); // all mounted ip-date-display elements re-render
+```