@instruments/materia-ui 0.4.9 → 0.4.10

package/agent-docs.md

@@ -14,7 +14,7 @@ Do and don't guidance for coding agents, one section per component, taken from `
 - Import icons through `Icon` and primitives through these components, never from `lucide-react` or `@base-ui/react` directly.
 - Check your work with the `materia-ui-lint` class scanner (`--all` for every rule). The Oxlint preset is `@instruments/materia-ui/lint/oxlint`.
 
-Documented components: 197
+Documented components: 198
 
 ## AccordionRoot
 
@@ -88,7 +88,7 @@ Constrains its content to a fixed width-to-height ratio, sizing itself to the av
 
 AttributeCard UI component. Import from "@instruments/materia-ui/compositions/attribute-card".
 
-- Use `AttributeCard` for a single label + prominent value stat tile (a KPI/metric); for many key/value pairs about one entity reach for `DescriptionList` instead.
+- Use `AttributeCard` for a single label + prominent value stat tile (a KPI/metric); for many key/value pairs about one entity reach for `DescriptionList` instead, and for a bare figure without a card, `Stat`.
 - Pass a Lucide component to `icon` (e.g. `RulerIcon`), not a rendered `<Icon/>` - it is handed to the internal `Icon` at a fixed `sm` size.
 - This is a preset composition of `Card`; restyle via the surrounding layout rather than reaching inside - for a bespoke layout compose `Card`/`CardContent` directly.
 
@@ -1782,6 +1782,15 @@ Orchestrates staggered entrance animations for child `StaggerItem` components. U
 - Tune rhythm with `stagger` (gap between items) and `delay` (lead-in) on the parent, rather than hand-setting per-child transition delays.
 - Needs `ReducedMotionProvider` in the tree so the orchestrated entrance both runs and honours the reduced-motion setting.
 
+## Stat
+
+`@instruments/materia-ui/components/stat`
+
+A figure, what it measures and where it comes from, value first. The component owns the type of all three, so a page's figures match without setting a size or weight at the call site. Import from "@instruments/materia-ui/components/stat".
+
+- Use `Stat` for a bare figure in running layout (a row of results, a cover, beside a chart); for a label-first tile in its own card reach for `AttributeCard`.
+- Keep `value` to the figure alone ("24", "1,284", "3–5") and put the sentence in `label`; `note` is for the source or date window, not a second label.
+
 ## Stepper
 
 `@instruments/materia-ui/components/stepper`

package/dist/components/stat/stat-root.d.ts

@@ -0,0 +1,32 @@
+import type * as React from "react";
+/** The sizes a Stat comes in: `base` sits among other content, `lg` leads a page or a section. */
+export declare const STAT_SIZES: readonly ["base", "lg"];
+/** A size a Stat comes in; see {@link STAT_SIZES}. */
+export type StatSize = (typeof STAT_SIZES)[number];
+interface StatProps {
+    /** CSS class name */
+    className?: string;
+    /** What the value measures, set under it. */
+    label?: React.ReactNode;
+    /** Where the value comes from, set small and muted under the label. */
+    note?: React.ReactNode;
+    /**
+     * `base` for a figure among other content (a table cell, a side panel); `lg` for one that leads a page or section.
+     * @default "base"
+     */
+    size?: StatSize;
+    /** The figure itself: a number, a percentage, a ratio. */
+    value: React.ReactNode;
+}
+/**
+ * A figure, what it measures and where it comes from, value first. The component owns the type of all three, so a
+ * page's figures match without setting a size or weight at the call site.
+ * Import from "@instruments/materia-ui/components/stat".
+ *
+ * @bestPractice Use `Stat` for a bare figure in running layout (a row of results, a cover, beside a chart); for a label-first tile in its own card reach for `AttributeCard`.
+ * @bestPractice Keep `value` to the figure alone ("24", "1,284", "3–5") and put the sentence in `label`; `note` is for the source or date window, not a second label.
+ * @category data
+ */
+declare const Stat: ({ value, label, note, size, className }: StatProps) => React.JSX.Element;
+export type { StatProps };
+export { Stat };

package/dist/components/stat/stat-root.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Stack } from "../stack.js";
+import { Text } from "../text.js";
+/** The sizes a Stat comes in: `base` sits among other content, `lg` leads a page or a section. */
+export const STAT_SIZES = ["base", "lg"];
+/** The value's role at each size. `heading-lg` is past the sizes Text takes, so the value sets its own role. */
+const VALUE_CLASSES = {
+    base: "text-subheading-lg",
+    lg: "text-heading-lg",
+};
+/** The label's role at each size. */
+const LABEL_SIZES = {
+    base: "paragraph-sm",
+    lg: "paragraph",
+};
+const isSet = (node) => node !== undefined && node !== null && node !== "";
+/**
+ * A figure, what it measures and where it comes from, value first. The component owns the type of all three, so a
+ * page's figures match without setting a size or weight at the call site.
+ * Import from "@instruments/materia-ui/components/stat".
+ *
+ * @bestPractice Use `Stat` for a bare figure in running layout (a row of results, a cover, beside a chart); for a label-first tile in its own card reach for `AttributeCard`.
+ * @bestPractice Keep `value` to the figure alone ("24", "1,284", "3–5") and put the sentence in `label`; `note` is for the source or date window, not a second label.
+ * @category data
+ */
+const Stat = ({ value, label, note, size = "base", className }) => (_jsxs(Stack, { className: className, "data-component": "stat", "data-slot": "stat", gap: "xs", children: [_jsx("p", { className: cn("trim-both font-medium text-pretty", VALUE_CLASSES[size]), "data-slot": "stat-value", children: value }), isSet(label) && (_jsx(Text, { "data-slot": "stat-label", size: LABEL_SIZES[size], children: label })), isSet(note) && (_jsx(Text, { "data-slot": "stat-note", size: "caption", variant: "muted", children: note }))] }));
+export { Stat };

package/dist/components/stat.d.ts

@@ -0,0 +1,2 @@
+export type { StatProps, StatSize } from "./stat/stat-root.js";
+export { STAT_SIZES, Stat } from "./stat/stat-root.js";

package/dist/components/stat.js

@@ -0,0 +1 @@
+export { STAT_SIZES, Stat } from "./stat/stat-root.js";

package/dist/compositions/attribute-card.d.ts

@@ -16,7 +16,7 @@ interface AttributeCardProps {
  * AttributeCard UI component.
  * Import from "@instruments/materia-ui/compositions/attribute-card".
  *
- * @bestPractice Use `AttributeCard` for a single label + prominent value stat tile (a KPI/metric); for many key/value pairs about one entity reach for `DescriptionList` instead.
+ * @bestPractice Use `AttributeCard` for a single label + prominent value stat tile (a KPI/metric); for many key/value pairs about one entity reach for `DescriptionList` instead, and for a bare figure without a card, `Stat`.
  * @bestPractice Pass a Lucide component to `icon` (e.g. `RulerIcon`), not a rendered `<Icon/>` - it is handed to the internal `Icon` at a fixed `sm` size.
  * @bestPractice This is a preset composition of `Card`; restyle via the surrounding layout rather than reaching inside - for a bespoke layout compose `Card`/`CardContent` directly.
  * @category catalogue

package/dist/compositions/attribute-card.js

@@ -7,7 +7,7 @@ import { Icon } from "../components/icon.js";
  * AttributeCard UI component.
  * Import from "@instruments/materia-ui/compositions/attribute-card".
  *
- * @bestPractice Use `AttributeCard` for a single label + prominent value stat tile (a KPI/metric); for many key/value pairs about one entity reach for `DescriptionList` instead.
+ * @bestPractice Use `AttributeCard` for a single label + prominent value stat tile (a KPI/metric); for many key/value pairs about one entity reach for `DescriptionList` instead, and for a bare figure without a card, `Stat`.
  * @bestPractice Pass a Lucide component to `icon` (e.g. `RulerIcon`), not a rendered `<Icon/>` - it is handed to the internal `Icon` at a fixed `sm` size.
  * @bestPractice This is a preset composition of `Card`; restyle via the surrounding layout rather than reaching inside - for a bespoke layout compose `Card`/`CardContent` directly.
  * @category catalogue

package/dist/data/docs-manifest.d.ts

@@ -74,5 +74,5 @@ export interface DocsManifest {
     storybook: DocsStorybookInventory;
 }
 /** The slug of every documented component and composition. */
-export type DocsUnitSlug = "accordion" | "alert" | "alert-dialog" | "anchor" | "animated-number" | "aspect-ratio" | "attribute-card" | "avatar" | "badge" | "border-beam" | "box" | "breadcrumb" | "button" | "button-group" | "calendar" | "card" | "card-grid" | "carousel" | "center" | "chart" | "checkbox" | "checkbox-card" | "checkbox-field" | "code" | "collapsible" | "color-palette" | "color-wheel" | "combobox" | "command" | "container" | "context-menu" | "cookie-banner" | "country-combobox" | "country-select" | "data-grid" | "data-grid-column-filter" | "data-grid-column-header" | "data-grid-column-visibility" | "data-grid-pagination" | "data-grid-table" | "delivery-banner" | "description-list" | "dialog" | "document-list" | "dot" | "dot-matrix-loader" | "drawer" | "dropdown-menu" | "easing-curve" | "editorial-card" | "empty" | "empty-state" | "error-boundary" | "error-state" | "expand-button" | "expandable-text" | "fade-overlay" | "field" | "file-upload" | "flex" | "folder-tile" | "gallery" | "grid" | "group" | "heading" | "hotspot-indicator" | "hover-card" | "icon" | "icon-box" | "icon-card" | "icon-morph" | "identified-surface" | "input" | "input-card" | "input-group" | "input-otp" | "item" | "kbd" | "label" | "loading-state" | "location-input" | "logo" | "logotype" | "marquee-text" | "media-frame" | "mega-menu" | "menu-item" | "menubar" | "mobile-navigation" | "month-year-picker" | "morph-dialog" | "motion-config" | "native-select" | "navigation-menu" | "page-header" | "page-toolbar" | "pagination" | "phone-input" | "pill" | "pixel-loader" | "popover" | "product-card" | "product-specifications-selector" | "progress" | "progress-dots" | "prompt-panel" | "quantity-control" | "quick-view" | "radio" | "radio-card" | "radio-group" | "requirement-item" | "resizable" | "scrim" | "scroll-area" | "scroll-fade" | "scroll-frame" | "search-input" | "section" | "section-header" | "segmented-control" | "select" | "separator" | "settings-card" | "sheet" | "shimmer" | "shine" | "sidebar" | "sidepanel" | "simple-grid" | "site-footer" | "skeleton" | "slider" | "social-icon" | "space" | "spinner" | "stack" | "stagger" | "stepper" | "streaming-text" | "sub-navigation" | "success-tick-ripple" | "swatch" | "swatch-fan" | "swatch-group" | "swatch-selector" | "switch" | "tab-navigation" | "table" | "tabs" | "tag" | "tag-selector" | "text" | "textarea" | "thinking-loader" | "thinking-orb" | "thinking-trace" | "time-slot-picker" | "toast" | "toggle" | "toggle-group" | "tooltip" | "variant-selector" | "verge" | "visually-hidden" | "voice";
+export type DocsUnitSlug = "accordion" | "alert" | "alert-dialog" | "anchor" | "animated-number" | "aspect-ratio" | "attribute-card" | "avatar" | "badge" | "border-beam" | "box" | "breadcrumb" | "button" | "button-group" | "calendar" | "card" | "card-grid" | "carousel" | "center" | "chart" | "checkbox" | "checkbox-card" | "checkbox-field" | "code" | "collapsible" | "color-palette" | "color-wheel" | "combobox" | "command" | "container" | "context-menu" | "cookie-banner" | "country-combobox" | "country-select" | "data-grid" | "data-grid-column-filter" | "data-grid-column-header" | "data-grid-column-visibility" | "data-grid-pagination" | "data-grid-table" | "delivery-banner" | "description-list" | "dialog" | "document-list" | "dot" | "dot-matrix-loader" | "drawer" | "dropdown-menu" | "easing-curve" | "editorial-card" | "empty" | "empty-state" | "error-boundary" | "error-state" | "expand-button" | "expandable-text" | "fade-overlay" | "field" | "file-upload" | "flex" | "folder-tile" | "gallery" | "grid" | "group" | "heading" | "hotspot-indicator" | "hover-card" | "icon" | "icon-box" | "icon-card" | "icon-morph" | "identified-surface" | "input" | "input-card" | "input-group" | "input-otp" | "item" | "kbd" | "label" | "loading-state" | "location-input" | "logo" | "logotype" | "marquee-text" | "media-frame" | "mega-menu" | "menu-item" | "menubar" | "mobile-navigation" | "month-year-picker" | "morph-dialog" | "motion-config" | "native-select" | "navigation-menu" | "page-header" | "page-toolbar" | "pagination" | "phone-input" | "pill" | "pixel-loader" | "popover" | "product-card" | "product-specifications-selector" | "progress" | "progress-dots" | "prompt-panel" | "quantity-control" | "quick-view" | "radio" | "radio-card" | "radio-group" | "requirement-item" | "resizable" | "scrim" | "scroll-area" | "scroll-fade" | "scroll-frame" | "search-input" | "section" | "section-header" | "segmented-control" | "select" | "separator" | "settings-card" | "sheet" | "shimmer" | "shine" | "sidebar" | "sidepanel" | "simple-grid" | "site-footer" | "skeleton" | "slider" | "social-icon" | "space" | "spinner" | "stack" | "stagger" | "stat" | "stepper" | "streaming-text" | "sub-navigation" | "success-tick-ripple" | "swatch" | "swatch-fan" | "swatch-group" | "swatch-selector" | "switch" | "tab-navigation" | "table" | "tabs" | "tag" | "tag-selector" | "text" | "textarea" | "thinking-loader" | "thinking-orb" | "thinking-trace" | "time-slot-picker" | "toast" | "toggle" | "toggle-group" | "tooltip" | "variant-selector" | "verge" | "visually-hidden" | "voice";
 export declare const docsManifest: DocsManifest;

package/dist/data/docs-manifest.js

@@ -11403,6 +11403,7 @@ export const docsManifest = {
                 "sidepanel",
                 "site-footer",
                 "skeleton",
+                "stat",
             ],
         },
         {
@@ -11465,6 +11466,74 @@ export const docsManifest = {
             uses: [],
             usedBy: [],
         },
+        {
+            slug: "stat",
+            module: "components/stat",
+            title: "Stat",
+            category: "data",
+            description: 'A figure, what it measures and where it comes from, value first. The component owns the type of all three, so a\npage\'s figures match without setting a size or weight at the call site.\nImport from "@instruments/materia-ui/components/stat".',
+            exports: [
+                {
+                    name: "Stat",
+                    kind: "component",
+                    props: [
+                        {
+                            name: "className",
+                            type: "string",
+                            required: false,
+                            description: "CSS class name",
+                        },
+                        {
+                            name: "label",
+                            type: "React.ReactNode",
+                            required: false,
+                            description: "What the value measures, set under it.",
+                        },
+                        {
+                            name: "note",
+                            type: "React.ReactNode",
+                            required: false,
+                            description: "Where the value comes from, set small and muted under the label.",
+                        },
+                        {
+                            name: "size",
+                            type: '"base" | "lg"',
+                            required: false,
+                            defaultValue: '"base"',
+                            description: "`base` for a figure among other content (a table cell, a side panel); `lg` for one that leads a page or section.",
+                        },
+                        {
+                            name: "value",
+                            type: "React.ReactNode",
+                            required: true,
+                            description: "The figure itself: a number, a percentage, a ratio.",
+                        },
+                    ],
+                },
+                {
+                    name: "STAT_SIZES",
+                    kind: "const",
+                    props: [],
+                },
+                {
+                    name: "StatProps",
+                    kind: "interface",
+                    props: [],
+                },
+                {
+                    name: "StatSize",
+                    kind: "type",
+                    props: [],
+                },
+            ],
+            bestPractices: [
+                "Use `Stat` for a bare figure in running layout (a row of results, a cover, beside a chart); for a label-first tile in its own card reach for `AttributeCard`.",
+                'Keep `value` to the figure alone ("24", "1,284", "3–5") and put the sentence in `label`; `note` is for the source or date window, not a second label.',
+            ],
+            keywords: [],
+            uses: ["stack", "text"],
+            usedBy: [],
+        },
         {
             slug: "stepper",
             module: "components/stepper",
@@ -12839,6 +12908,7 @@ export const docsManifest = {
                 "section-header",
                 "site-footer",
                 "slider",
+                "stat",
                 "streaming-text",
                 "thinking-trace",
             ],
@@ -13876,7 +13946,7 @@ export const docsManifest = {
                 },
             ],
             bestPractices: [
-                "Use `AttributeCard` for a single label + prominent value stat tile (a KPI/metric); for many key/value pairs about one entity reach for `DescriptionList` instead.",
+                "Use `AttributeCard` for a single label + prominent value stat tile (a KPI/metric); for many key/value pairs about one entity reach for `DescriptionList` instead, and for a bare figure without a card, `Stat`.",
                 "Pass a Lucide component to `icon` (e.g. `RulerIcon`), not a rendered `<Icon/>` - it is handed to the internal `Icon` at a fixed `sm` size.",
                 "This is a preset composition of `Card`; restyle via the surrounding layout rather than reaching inside - for a bespoke layout compose `Card`/`CardContent` directly.",
             ],
@@ -23834,7 +23904,7 @@ export const docsManifest = {
     storybook: {
         addons: ["@storybook/addon-docs", "@storybook/react-vite"],
         anatomyFiles: 31,
-        storyFiles: 172,
+        storyFiles: 173,
         storiesWithPlay: 63,
     },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruments/materia-ui",
-  "version": "0.4.9",
+  "version": "0.4.10",
   "description": "Materia design system: React components, tokens and Tailwind v4 styles.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
@@ -462,6 +462,10 @@
       "types": "./dist/components/stagger.d.ts",
       "default": "./dist/components/stagger.js"
     },
+    "./components/stat": {
+      "types": "./dist/components/stat.d.ts",
+      "default": "./dist/components/stat.js"
+    },
     "./components/stepper": {
       "types": "./dist/components/stepper.d.ts",
       "default": "./dist/components/stepper.js"