(\n \n ⚠ Sensor unreachable\n {error}\n
\n )}\n renderEmpty={() => — no reading yet —}\n/>\n\n (\n \n ⚠ Sensor unreachable\n {error}\n
\n )}\n renderEmpty={() => — no reading yet —}\n/>\n\n// commonProps = { node, variable: \"humidity\" }\n```\n\n`renderError` receives the raw error message string; `renderEmpty` takes no arguments. When either is provided, it fully replaces the default `error`/`empty` slot rendering — the corresponding `styles.error`/`styles.empty` classes are ignored in that case, since there's no default element left for them to apply to.\n\n#### Reacting to errors/empty state via `onDataChange`\n\n`onDataChange` receives a second argument describing which state just occurred, so you can react to errors or empty data the same way you already react to values:\n\n```tsx\n {\n if (meta.kind === \"error\") {\n return { renderError: () => Offline };\n }\n if (meta.kind === \"empty\") {\n return { renderEmpty: () => Waiting for first reading… };\n }\n if (!data) return;\n if (data.value > 80) {\n return { title: \"High Humidity\", theme: \"dark\" };\n }\n }}\n/>\n\n {\n if (meta.kind === \"error\") {\n return { renderError: () => Offline };\n }\n if (meta.kind === \"empty\") {\n return { renderEmpty: () => Waiting for first reading… };\n }\n if (!data) return;\n if (data.value > 80) {\n return { color: \"#ef4444\", theme: \"dark\" };\n }\n }}\n/>\n\n// commonProps = { node, variable: \"humidity\" }\n```\n\n`meta.kind` is one of `\"success\"`, `\"error\"`, or `\"empty\"`; `meta.error` is present only when `meta.kind === \"error\"`, carrying the underlying error message.\n\nThis is backwards compatible — existing `onDataChange={(data) => {...}}` callbacks that ignore the second argument continue to work unchanged.\n\n---\n\n### Formatters export\n\nThe formatting helpers used internally are also available as a standalone import, for composing into your own `labelText`/`formatValue` functions — usable with either widget:\n\n```tsx\nimport { relativeTime } from \"@anedyasystems/anedya-widgets-react/formatters\";\n```\n\n| Export | Signature | Description |\n| -------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |\n| `relativeTime` | `(timestamp: number, locale?: string) => string` | Converts a timestamp into a human-relative string (`\"5 minutes ago\"`). Accepts seconds or milliseconds. |\n\n---\n\n### Sizing\n\n#### AnedyaCard\n\n`width` / `height` / `minWidth` / `maxWidth` are plain props, applied as inline styles on the container — independent of the whole `styles`/theme system:\n\n```jsx\n\n```\n\n##### `height` has two distinct modes\n\nWhether you pass `height` changes how the card behaves — this is intentional, not a quirk:\n\n| | Behavior |\n| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **`height` omitted** | The card **auto-grows** to fit its content. If `formatValue`/`labelText` produce long text that wraps, the card simply becomes taller. Sizing scales with **width only**. |\n| **`height` passed** | The card becomes a **fixed-size box**. Sizing scales with **both width and height** (see [Responsive sizing](#responsive-sizing)). If content is too tall to fit (e.g. a long wrapped value at a small height), it is **clipped**, not overflowed — the card will not grow past the height you gave it. |\n\n```jsx\n// Auto-height: card grows to fit content, whatever that content turns out to be\n\n\n// Fixed-height: card is exactly 300px tall; content that doesn't fit is clipped\n\n```\n\nIf you're using a `formatValue` that can produce long strings, either don't pass a fixed `height` (let the card grow to fit), or pass a `height` generous enough for the wrapped text at your chosen `width`.\n\n#### AnedyaGauge\n\n```jsx\n\n // shorthand: sets width AND height to the same value (a square gauge)\n```\n\n`size` takes priority over `width`/`height` when both are set. Without `size` or `height`, the gauge fills its container's width and derives a proportional height automatically (unless `aspectRatio` is set).\n\n| Prop | Type | Description |\n| ------------- | -------- | -------------------------------------------------------------------------- |\n| `size` | `number` | Shorthand for equal `width`/`height` — a fixed square gauge |\n| `width` | `number` | Container width in px |\n| `height` | `number` | Container height in px |\n| `minWidth` | `number` | Minimum container width in px |\n| `maxWidth` | `number` | Maximum container width in px |\n| `minHeight` | `number` | Minimum container height in px |\n| `maxHeight` | `number` | Maximum container height in px |\n| `aspectRatio` | `number` | Width-to-height ratio used when neither `size` nor `height` is set |\n\nUnlike Card, the gauge doesn't clip content past a fixed `height` — instead, the arc's radius and internal spacing shrink to fit whatever box is available (see [Responsive sizing](#responsive-sizing) below).\n\n---\n\n### Responsive sizing\n\nThe widget automatically scales its internal spacing and typography using **CSS Container Queries** — based on the widget's own rendered size, not the browser viewport.\n\nBy default the following properties scale automatically:\n\n- container padding\n- title font size\n- value font size\n- unit font size\n- label font size\n- spacing (`gap`)\n- arc thickness (gauge bar thickness)\n\n**When `height` is omitted**, scaling responds to the container's **width only** (`cqw`).\n\n**When `height` is passed**, scaling responds to **both width and height** (`cqw` + `cqh`) — a taller fixed-size container renders bigger text/gaps than a shorter one at the same width, in addition to width's usual effect. For the `AnedyaGauge`, the arc radius and thickness are also computed from the available container size, so they resize automatically.\n\nA widget inside a narrow dashboard column will use smaller typography than the same widget rendered full-width, even on the same screen — this behavior is built in and needs no configuration.\n\n#### Overriding responsive sizing\n\nIf you provide your own font-size utility for a slot, you're opting out of the default responsive sizing for that slot.\n\n```tsx\n// AnedyaCard\n\n\n// AnedyaGauge\n\n```\n\nThe value will always render at `text-6xl`. Likewise, responsive Tailwind classes (`text-2xl md:text-5xl`) take precedence over the widget's default responsive sizing — your classes always win over the widget defaults.\n\n> **AnedyaGauge note:** the arc's radius itself is handled separately from these CSS variables (it's a geometry calculation, not a font size) — it auto-fits to whatever space is left after padding and, if enabled, tick-mark space is subtracted, capped by `arc.radius` when you set one explicitly.\n\n---\n\n### Loading & error states\n\n#### AnedyaCard\n\nWhile the initial fetch is in flight, the card renders **skeleton loaders** in place of the value and label — pulsing placeholder blocks sized to match each slot's current font-size variable (`var(--anedya-card-value-size)` / `var(--anedya-card-label-size)`), so the skeleton scales along with the card exactly like the real content would.\n\nIf the fetch fails or no data is available, the card renders the error message text in place of the value (title still renders normally).\n\nNeither state currently accepts style overrides via `styles` — flag it if you need to customize their appearance.\n\n#### AnedyaGauge\n\nWhile the initial fetch is in flight, the gauge renders the same kind of pulsing skeleton blocks in place of the value and label (sized against `var(--anedya-gauge-value-size)` / `var(--anedya-gauge-label-size)`), and the arc/needle themselves render at reduced opacity rather than disappearing, so the gauge's shape stays visible while data loads.\n\nIf the fetch fails or no data is available, the error message (or `renderError`/`renderEmpty` output) replaces the value/label block; the arc still renders behind it at the gauge's minimum value.\n\n---\n\n### Other props\n\n#### AnedyaCard\n\n| Prop | Type | Description |\n| --------------- | -------- | ------------------------------------------------------------------------------------ |\n| `title` | `string` | Card title. Default: `\"Latest Value\"` |\n| `value` | `number` | Manual/controlled value. Used as the initial value, or the only value if no `node` is given |\n| `unit` | `string` | Unit suffix shown next to the value |\n| `decimalPlaces` | `number` | Decimal places for the displayed value (used only if `formatValue` isn't provided) |\n\n#### AnedyaGauge\n\n| Prop | Type | Description |\n| --------------- | --------- | -------------------------------------------------------------------------------------------------- |\n| `title` | `string` | Gauge title. Default: `\"Latest Value\"` |\n| `value` | `number` | Manual/controlled value. Used as the initial value, or the only value if no `node` is given |\n| `min` | `number` | Minimum of the gauge's range. Default: `0` |\n| `max` | `number` | Maximum of the gauge's range. Default: `100` |\n| `unit` | `string` | Unit suffix shown next to the value |\n| `decimalPlaces` | `number` | Decimal places for the displayed value (used only if `formatValue` isn't provided) |\n\n---\n\n## Stylesheet import\n\nThis SDK ships pre-compiled CSS alongside its JavaScript — you don't need Tailwind configured in your own project for these widgets to render correctly, even if you don't use Tailwind at all.\n\n**Import the stylesheet once**, anywhere in your app's entry point (e.g. `main.tsx`, `App.tsx`, or your global styles file):\n\n```jsx\nimport \"@anedyasystems/anedya-widgets-react/styles.css\";\n```\n\nThat's the entire integration on your end. No `content` glob changes to your `tailwind.config`, no build coordination, nothing else required — every widget in this SDK will render fully styled as soon as this import is present.\n\n> **If styles aren't appearing:** double-check the import path matches your installed package name exactly, and that it's imported somewhere that actually runs before your widgets render (e.g. not inside a conditionally-loaded file). If you're using a bundler with strict CSS module resolution, confirm it supports subpath imports from `node_modules` (most modern bundlers — Vite, Webpack 5+, Next.js — do, out of the box).","readmeFilename":"README.md"}![\"Logo\"](\"https://cdn.anedya.io/anedya_black_banner.png\")
\n![\"PyPI\"](\"https://img.shields.io/npm/v/%40anedyasystems%2Fanedya-widgets-react?style=for-the-badge\")
](https://www.npmjs.com/package/@anedyasystems/anedya-widgets-react) [![\"Anedya](\"https://img.shields.io/badge/Anedya-Documentation-blue?style=for-the-badge\"){kind=icon}
](https://docs.anedya.io?utm_source=github&utm_medium=link&utm_campaign=github-sdk&utm_content=js)\n\n\n