{ "tag": "ed-widget-news", "kind": "widget", "summary": "Shows eurodata release news and useful information to users in a panel inside the product.", "status": "experimental", "since": "1.0", "docs": "https://test-apps.eurodata.de/a/eurodata-ui/docs/widgets/news/", "usage": "https://test-apps.eurodata.de/a/eurodata-ui/docs/widgets/news/usage/", "playwright": "getByTestId('…')", "dependencies": [ "ed-button", "ed-icon", "ed-dialog", "ed-drawer", "ed-carousel", "ed-intersection-observer", "ed-badge", "ed-divider" ], "use": [ "A user learning what is new in the product after an update, without leaving the screen they are on", "Announcing release notes or helpful tips to all users of a product from one central place", "A news panel that adapts to mobile screens, switching its view at a configurable breakpoint", "Only when the user explicitly asks for it, coordinated with the DMS team" ], "notFor": [ { "when": "A message about the current action, such as saved or failed", "instead": "a [Toast](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/toast-item) or a [Notification](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/notification)" }, { "when": "A persistent notice about the state of one screen", "instead": "a [Notification](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/notification)" } ], "rules": [], "api": { "attributes": [ { "name": "open", "property": "open", "type": "boolean", "default": "false", "description": "Indicates whether the dialog is open. Toggle this attribute to show and hide the dialog. Open can never be initially be true since the session must be internally validated before allowing open to be true." }, { "name": "label", "property": "label", "type": "string", "description": "The dialog's label as displayed in the header." }, { "name": "base-url", "property": "baseUrl", "type": "string", "description": "The base url for the news service" }, { "name": "mobile-breakpoint", "property": "mobileBreakpoint", "type": "string", "default": "'768px'", "description": "At what widget width to collapse the sidebar into a hamburger-toggled drawer.\nAccepts both numbers (interpreted as px) and CSS lengths (e.g. `48em`), resolved against the root element.\nMatches the convention used by `ed-app`'s `mobile-breakpoint`." }, { "name": "view", "property": "view", "type": "'mobile' | 'desktop'", "default": "'desktop'", "description": "Reflects the current layout view based on the widget's own width. Driven by `mobile-breakpoint`.\nDefault `'desktop'` so SSR markup doesn't flash a mobile layout." }, { "name": "dir", "property": "dir", "type": "string" }, { "name": "lang", "property": "lang", "type": "string" } ], "properties": [ { "name": "session", "type": "string", "description": "The session token for the news service.\n\n**Property only** — deliberately not settable through an HTML attribute, so the token never\nsits in the DOM where page scripts, browser extensions, session-replay tools and error\ntrackers that snapshot markup would read it. Assign it in JavaScript:\n`document.querySelector('ed-widget-news').session = token`." } ], "methods": [], "events": [ { "name": "ed-session-expiring", "react": "onEdSessionExpiring", "type": "{ remainingTime: number, cause: 'scheduled' | 'immediate' }", "description": "Fires while the session is still usable, so a replacement can be fetched before the user hits an error. `event.detail.cause` says which case it is: `'scheduled'` (the one-minute warning of a session that was valid for longer — renew freely) or `'immediate'` (the session was already inside the warning window when it was validated, so there was no minute to wait for). **Do not renew unconditionally on `'immediate'`.** A source that hands out a nearly-expired session tends to do it again, and renewing on every warning loops." }, { "name": "ed-session-expired", "react": "onEdSessionExpired", "type": "{ remainingTime: number, cause: 'expired' | 'invalid' | 'error' }", "description": "Fires when the session can no longer be used. `event.detail.cause` says why: `'expired'` (the session was valid and its lifetime elapsed — re-authenticating is appropriate), `'invalid'` (the service rejected the token — HTTP 401/403 or no future `validTo`), or `'error'` (the validation request failed — network error, server error, malformed response). **Only re-authenticate on `'expired'`.** Requesting a new session on `'invalid'`/`'error'` and re-assigning `session` loops endlessly while the token stays bad or the service is down. Cancelable; calling `preventDefault()` keeps the widget running." }, { "name": "ed-news-count-changed", "react": "onEdNewsCountChanged", "type": "{ count: number }", "description": "This event fires when the total number of news items is determined and returns the exact number. It fires when the session changes (that also means initially). You can get the amount with `event.detail.count`. Use this to hide or disable your trigger button when the count is 0." }, { "name": "ed-unread-news-count-changed", "react": "onEdUnreadNewsCountChanged", "type": "{ count: number }", "description": "This event fires when the amount of unread news items for the user is changed and returns the exact number. The amount of unread news is calculated when the session changes (that also means initially), when the open attribute is set to true or when the user selects an unseen news object and thus reducing the count by one. You can get the amount with `event.detail.count`." }, { "name": "ed-show", "react": "onEdShow", "description": "Emitted when the news widget opens. Cancelable; calling `preventDefault()` keeps it closed." }, { "name": "ed-after-show", "react": "onEdAfterShow", "description": "Emitted after the news widget opens and its open animation completes." }, { "name": "ed-hide", "react": "onEdHide", "description": "Emitted when the news widget is requested to close (close button, [[Escape]], light-dismiss or setting `open` to `false`). Cancelable; calling `preventDefault()` keeps it open. Cancelable; calling `preventDefault()` keeps it open." }, { "name": "ed-after-hide", "react": "onEdAfterHide", "description": "Emitted after the news widget closes and its close animation completes." } ], "slots": [], "cssProperties": [ { "name": "--ed-news-height", "default": "50rem", "description": "The height of the news dialog. Clamped by the dialog's own max-height on short viewports." } ], "parts": [ { "name": "base", "description": "The components base wrapper, an ed-dialog element" }, { "name": "aside", "description": "The components aside that holds the navigation on desktop; becomes a collapsible drawer on narrow widths" }, { "name": "sidebar", "description": "The navigation wrapper" }, { "name": "sidebar-entry", "description": "The items inside the navigation wrapper" }, { "name": "external-button", "description": "External button, that shows depending on the news object" }, { "name": "menu-toggle", "description": "The hamburger button that opens the navigation drawer on narrow widths" }, { "name": "close-button", "description": "The close button that closes the dialog" } ], "states": [] }, "import": "import '@eurodata/eurodata-ui/dist/widgets/news/news.js';", "react": { "component": "EdWidgetNews", "import": "import EdWidgetNews from '@eurodata/eurodata-ui/dist/react/widget-news/index.js';" } }