{ "version": "0.2.0-preview.1", "content_digest": "70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721", "status": "preview", "authority": { "repository": "cloakedinc/design", "path": "packages/design-system", "catalog": "packages/design-system/catalog.json", "status": "preview" }, "provenance": { "repo": "cloakedinc/automation", "commit": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1", "path": "packages/design-system", "imported_spec_status": "approved" }, "adaptations": [ { "id": "button-content-gap", "status": "preview", "description": "Use the specification's 4px content gap instead of the inherited 8px implementation gap." }, { "id": "keyboard-focus", "status": "preview", "description": "Add visible Button and Input keyboard focus and an overridable inset focus default for shared button resets, including FAQ cards and ListItem rows." }, { "id": "supporting-text-contrast", "status": "preview", "description": "Map light secondary text to the existing grey-04-strong primitive for readable helper text on white and cream." }, { "id": "danger-text-contrast", "status": "preview", "description": "Separate readable danger text/borders from destructive fills; preserve the primary danger-button fill and label pair." }, { "id": "preview-status", "status": "preview", "description": "Local components, specs and token adaptations await human sign-off; upstream approved status is provenance only." }, { "id": "motion-comparison-accessibility", "status": "preview", "description": "Preserve the original MotionShowcase comparisons while requiring explicit replay, responding to live reduced-motion changes, and keeping duration tracks usable on small screens." }, { "id": "list-item-ownership", "status": "preview", "description": "List owns listitem wrappers for its content rows, while section labels stay outside the row count and standalone rows retain their existing semantics." }, { "id": "card-delta-text-contrast", "status": "preview", "description": "Mix Card.Delta foregrounds from 60% existing tone solid and 40% primary text for readable contrast in both themes; preserve the four original tone fills." }, { "id": "carousel-keyboard-access", "status": "preview", "description": "Keep all native-scrolling carousel slide controls exposed to assistive technology and keyboard navigation; pause autoplay while focus is inside the carousel." } ], "id": "animatednumber", "name": "AnimatedNumber", "category": "Primitives", "summary": "A numeric readout that moves from its previous value to a new target while keeping the settled value accessible.", "documentation": { "summary": "A numeric readout that moves from its previous value to a new target while keeping the settled value accessible.", "guidance": [ { "heading": "Overview", "body": "A number that counts from its previous value to its new one whenever `value` changes, with a\nphysical ease-in-out ramp. It owns only the animation and formatting — wrap it in a `Text` (or\n`Card.Metric`) for typography and color." }, { "heading": "When to use", "body": "Reach for `AnimatedNumber` when a numeric readout _changes_ and the motion carries meaning — a stat\nthat ticks up as work completes, a counter reacting to user action, or a value scrubbed along a\nchart. In-app it backs the Home stat widgets (`ActionsTakenWidget`,\n`BlockedSpamCallsWidget`, `SsnMonitoringWidget`) and the automations `StatsRow`.\n\n- Rendering a **static number** that never animates? Just put it in `Text` — the tween is wasted (and\n `AnimatedNumber` deliberately does not animate on mount, so a value that never changes looks\n identical to plain text anyway).\n- Value updates **every frame** while a chart is scrubbed? Set `follow` so it glides toward the\n moving target instead of restarting a discrete tween on each change.\n\nIt animates in either direction and snaps instead of animating under `prefers-reduced-motion`." } ], "usage": [], "examples": [], "source": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.mdx", "status": "local-preview", "note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification." }, "source": { "path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.tsx", "code": "import React from 'react';\nimport { formatNumber } from '../../../utilities';\nimport { useReducedMotion } from '../../visualizations/useReducedMotion';\n\n// A physical counter spins further for a bigger jump, so scale the tween length\n// with the magnitude of the change (clamped) rather than using one fixed time.\nconst MIN_DURATION = 550;\nconst MAX_DURATION = 2000;\nconst MS_PER_UNIT = 1;\n\n// Fraction of the remaining distance covered each frame in follow mode. High\n// enough to feel responsive under the finger, low enough to still read as a glide.\nconst FOLLOW_SMOOTHING = 0.35;\n\n/**\n * Props for the animated counting number.\n */\nexport interface AnimatedNumberProps {\n /** Target value to display; a change from the current value animates toward it. */\n value: number;\n /**\n * Continuously ease toward `value` every frame instead of running a fixed\n * tween per change. Use this while a chart is being scrubbed: `value` changes\n * on every pointer move, and a per-change tween would restart faster than it\n * can advance (the number would freeze). Follow mode glides smoothly toward\n * the finger and settles when scrubbing stops.\n */\n follow?: boolean;\n /**\n * Fixed tween duration in milliseconds for discrete changes. Omit to let the\n * duration scale with how large the jump is, so small changes settle quickly\n * and big ones feel weightier. Ignored while `follow` is true.\n */\n duration?: number;\n /** Formats the numeric value for display; defaults to locale digit grouping. */\n format?: (value: number) => string;\n /** Selector on the ``. Its text is a mid-animation frame; `aria-label` holds the settled value. */\n testId?: string;\n}\n\n/**\n * Renders a number that counts from its previous value to its current one\n * whenever `value` changes, with a physical ease-in-out ramp (accelerate, then\n * coast to a stop). It owns only the animation and formatting — wrap it in a\n * `Text` (or a `Card.Metric`) for typography and color, e.g.\n * ``.\n *\n * It does not animate on mount (the number appears at rest), animates in either\n * direction, and snaps instead of animating under `prefers-reduced-motion`.\n */\nexport function AnimatedNumber({\n value,\n follow = false,\n duration,\n format = formatNumber,\n testId,\n}: AnimatedNumberProps) {\n const display = useTickingValue(value, follow, duration);\n\n // The label carries the settled target so assistive tech reports the true\n // value rather than a mid-animation frame (the text node is not aria-live, so\n // intermediate frames are never announced).\n return (\n \n {format(display)}\n \n );\n}\n\n/**\n * Drives the displayed value toward `target` via a single persistent rAF loop:\n * a duration-based ease for discrete changes, or per-frame smoothing while\n * `follow` is set. The loop is seeded from refs and never torn down on a target\n * change, so rapid updates (scrubbing) keep advancing instead of restarting.\n */\nfunction useTickingValue(target: number, follow: boolean, duration: number | undefined): number {\n const [display, setDisplay] = React.useState(target);\n const displayRef = React.useRef(target);\n const targetRef = React.useRef(target);\n const followRef = React.useRef(follow);\n const tweenStartRef = React.useRef(target);\n const tweenStartTimeRef = React.useRef();\n const tweenDurationRef = React.useRef(0);\n const frameRef = React.useRef();\n const reducedMotion = useReducedMotion();\n\n const step = React.useCallback((now: number) => {\n const from = displayRef.current;\n const to = targetRef.current;\n let next: number;\n\n if (followRef.current) {\n const eased = Math.round(from + (to - from) * FOLLOW_SMOOTHING);\n next = eased === from && from !== to ? from + Math.sign(to - from) : eased;\n } else {\n if (tweenStartTimeRef.current === undefined) {\n tweenStartTimeRef.current = now;\n }\n const progress = Math.min((now - tweenStartTimeRef.current) / tweenDurationRef.current, 1);\n next = Math.round(tweenStartRef.current + (to - tweenStartRef.current) * easeInOutQuint(progress));\n }\n\n // Frames are integer-rounded, so a non-integer target never satisfies the\n // `next === to` stop below — snap within half a unit so the rAF loop can end.\n if (Math.abs(next - to) <= 0.5) {\n next = to;\n }\n\n displayRef.current = next;\n setDisplay(next);\n\n frameRef.current = next === to ? undefined : requestAnimationFrame(step);\n }, []);\n\n React.useEffect(() => {\n targetRef.current = target;\n followRef.current = follow;\n\n if (displayRef.current === target && frameRef.current == null) {\n return;\n }\n\n if (reducedMotion) {\n if (frameRef.current) {\n cancelAnimationFrame(frameRef.current);\n frameRef.current = undefined;\n }\n displayRef.current = target;\n setDisplay(target);\n return;\n }\n\n // Seed a fresh discrete tween from wherever the number currently sits.\n // Skipped in follow mode, which reads target live each frame instead.\n if (!follow) {\n tweenStartRef.current = displayRef.current;\n tweenStartTimeRef.current = undefined;\n tweenDurationRef.current = duration ?? resolveDuration(target - displayRef.current);\n }\n\n if (frameRef.current == null) {\n frameRef.current = requestAnimationFrame(step);\n }\n }, [target, follow, duration, reducedMotion, step]);\n\n React.useEffect(\n () => () => {\n if (frameRef.current) {\n cancelAnimationFrame(frameRef.current);\n }\n },\n []\n );\n\n return display;\n}\n\n/**\n * Scales tween length with the size of the change, clamped so tiny updates stay\n * snappy and large jumps never drag on.\n */\nfunction resolveDuration(delta: number): number {\n return Math.min(MAX_DURATION, MIN_DURATION + Math.abs(delta) * MS_PER_UNIT);\n}\n\n/**\n * Quintic ease-in-out — a pronounced wind-up from rest and a long coast into the\n * target, for a heavy, high-momentum physical-counter feel.\n */\nfunction easeInOutQuint(t: number): number {\n return t < 0.5 ? 16 * t * t * t * t * t : 1 - (-2 * t + 2) ** 5 / 2;\n}\n" }, "spec": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "AnimatedNumber", "status": "preview", "version": "1.0.0", "summary": "A numeric readout that moves from its previous value to a new target while keeping the settled value accessible." }, "parts": [ { "id": "readout", "label": "Readout", "description": "Displays each formatted frame and carries the settled target as its accessible name." } ], "allowedDesignChoices": { "variants": { "base": { "label": "Base", "description": "The component owns number motion and formatting; its parent owns typography and color." } }, "sizes": {} }, "variants": [ { "id": "base", "label": "Base", "description": "A typography-neutral animated numeric readout.", "platforms": [ "ios", "android", "web" ] } ], "sizes": [], "measurements": [ { "id": "display-example-type-size", "label": "Display example type size", "kind": "exact", "token": "--cds-type-display-1-size", "value": 72, "unit": "px", "appliesTo": [ "readout", "display-example" ], "notes": "The primary Storybook example composes AnimatedNumber inside Text display-1; consumers may choose another Text variant." }, { "id": "intrinsic-width", "label": "Readout width", "kind": "automatic", "appliesTo": [ "readout" ], "notes": "Width follows the formatted frame and is not reserved to the target string." } ], "layout": { "alignment": "The inline readout follows its parent text baseline.", "flow": "One formatted number occupies the parent typography run.", "notes": [ "Compose the readout inside Text or Card.Metric; AnimatedNumber does not establish a text hierarchy." ] }, "typographyAndColor": { "typography": [ { "label": "Example metric", "description": "The documented metric example uses the largest display ramp.", "token": "--cds-type-display-1-size" } ], "colors": [ { "label": "Example foreground", "description": "The documented metric example uses the primary text role.", "token": "--cds-text-primary" } ] }, "states": [ { "id": "resting", "label": "Resting", "description": "Shows the target immediately on mount and after motion settles." }, { "id": "animating", "label": "Animating", "description": "Runs one eased tween from the current display to a discrete target." }, { "id": "following", "label": "Following", "description": "Continuously glides toward rapidly changing targets during chart scrubbing." }, { "id": "reduced-motion", "label": "Reduced motion", "description": "Snaps directly to each target without intermediate frames." } ], "behavior": [ { "label": "Discrete changes", "description": "Scale duration with the magnitude of the change unless an explicit duration is supplied." }, { "label": "Rapid changes", "description": "Use follow mode for pointer-driven values so repeated updates do not restart a fixed tween." }, { "label": "Formatting", "description": "Apply the formatter to both the visible frame and the settled accessible value." } ], "accessibility": [ { "label": "Settled value", "description": "Expose the target as the accessible name so assistive technology never announces intermediate frames." }, { "label": "No live-region churn", "description": "Do not announce every animation frame; a surrounding live region may announce a meaningful completed update." } ], "contentAdaptation": [ { "label": "Number formats", "description": "Accept locale grouping, currency, percentages, and other deterministic numeric formatters." }, { "label": "Changing width", "description": "Allow enough parent space for the longest expected formatted value to avoid adjacent layout jumps." } ], "motionHaptics": { "motion": [ { "label": "Counter motion", "description": "Accelerate from rest and coast into the target for discrete changes; follow mode stays responsive to scrubbing." }, { "label": "Reduced motion", "description": "Honor the platform reduced-motion preference by removing the tween." } ], "haptics": [ { "label": "No feedback", "description": "The readout is not interactive and does not request haptic feedback." } ] }, "platformDifferences": [] }, "spec_source": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.spec.json", "guidance_source": { "path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.mdx", "code": "import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';\nimport { ComponentSpec } from '../../../../.storybook/blocks';\nimport * as Stories from './AnimatedNumber.stories';\nimport animatedNumberSpec from './AnimatedNumber.spec.json';\n\n\n\n# AnimatedNumber\n\nA number that counts from its previous value to its new one whenever `value` changes, with a\nphysical ease-in-out ramp. It owns only the animation and formatting — wrap it in a `Text` (or\n`Card.Metric`) for typography and color.\n\n\n\n## When to use\n\nReach for `AnimatedNumber` when a numeric readout _changes_ and the motion carries meaning — a stat\nthat ticks up as work completes, a counter reacting to user action, or a value scrubbed along a\nchart. In-app it backs the Home stat widgets (`ActionsTakenWidget`,\n`BlockedSpamCallsWidget`, `SsnMonitoringWidget`) and the automations `StatsRow`.\n\n- Rendering a **static number** that never animates? Just put it in `Text` — the tween is wasted (and\n `AnimatedNumber` deliberately does not animate on mount, so a value that never changes looks\n identical to plain text anyway).\n- Value updates **every frame** while a chart is scrubbed? Set `follow` so it glides toward the\n moving target instead of restarting a discrete tween on each change.\n\nIt animates in either direction and snaps instead of animating under `prefers-reduced-motion`.\n\n\n\n## Design Guidelines\n\n\n\n## Props\n\n\n" }, "props": [ { "name": "value", "type": "number", "declared_type": "number", "required": true, "description": "Target value to display; a change from the current value animates toward it.", "source": { "path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.tsx", "line": 20 } }, { "name": "follow", "type": "boolean | undefined", "declared_type": "boolean", "required": false, "description": "Continuously ease toward `value` every frame instead of running a fixed\ntween per change. Use this while a chart is being scrubbed: `value` changes\non every pointer move, and a per-change tween would restart faster than it\ncan advance (the number would freeze). Follow mode glides smoothly toward\nthe finger and settles when scrubbing stops.", "source": { "path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.tsx", "line": 28 }, "values": [ false, true ], "values_complete": true, "default": "false", "default_kind": "source-expression" }, { "name": "duration", "type": "number | undefined", "declared_type": "number", "required": false, "description": "Fixed tween duration in milliseconds for discrete changes. Omit to let the\nduration scale with how large the jump is, so small changes settle quickly\nand big ones feel weightier. Ignored while `follow` is true.", "source": { "path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.tsx", "line": 34 } }, { "name": "format", "type": "((value: number) => string) | undefined", "declared_type": "(value: number) => string", "required": false, "description": "Formats the numeric value for display; defaults to locale digit grouping.", "source": { "path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.tsx", "line": 36 }, "default": "formatNumber", "default_kind": "source-expression" }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Selector on the ``. Its text is a mid-animation frame; `aria-label` holds the settled value.", "source": { "path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.tsx", "line": 38 } } ], "prop_shapes": {}, "examples": [], "tokens": [ { "name": "--cds-type-display-1-size", "light": "4.5rem", "dark": "4.5rem" }, { "name": "--cds-text-primary", "light": "#141410", "dark": "#f3f1ed" } ], "visual_reference": { "stories": [ { "id": "cloaked-design-system-primitives-animatednumber--playground", "name": "Playground", "title": "Cloaked Design System/Primitives/AnimatedNumber", "exportName": "Playground", "source_path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.stories.tsx", "source_digest": "2dad9645a59bc81f2263ec4e0e2cd2f8d2996952ca7ea37f57c00f9948095c8c", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-animatednumber--playground&viewMode=story" }, { "id": "cloaked-design-system-primitives-animatednumber--count-up-on-change", "name": "Count Up On Change", "title": "Cloaked Design System/Primitives/AnimatedNumber", "exportName": "CountUpOnChange", "source_path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.stories.tsx", "source_digest": "2dad9645a59bc81f2263ec4e0e2cd2f8d2996952ca7ea37f57c00f9948095c8c", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-animatednumber--count-up-on-change&viewMode=story" }, { "id": "cloaked-design-system-primitives-animatednumber--formatted", "name": "Formatted", "title": "Cloaked Design System/Primitives/AnimatedNumber", "exportName": "Formatted", "source_path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.stories.tsx", "source_digest": "2dad9645a59bc81f2263ec4e0e2cd2f8d2996952ca7ea37f57c00f9948095c8c", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-animatednumber--formatted&viewMode=story" }, { "id": "cloaked-design-system-primitives-animatednumber--scrub-tracking", "name": "Scrub Tracking", "title": "Cloaked Design System/Primitives/AnimatedNumber", "exportName": "ScrubTracking", "source_path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.stories.tsx", "source_digest": "2dad9645a59bc81f2263ec4e0e2cd2f8d2996952ca7ea37f57c00f9948095c8c", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-animatednumber--scrub-tracking&viewMode=story" } ], "name": "AnimatedNumber", "id": "animatednumber", "category": "Primitives" }, "stories": [ { "id": "cloaked-design-system-primitives-animatednumber--playground", "name": "Playground", "title": "Cloaked Design System/Primitives/AnimatedNumber", "exportName": "Playground", "source_path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.stories.tsx", "source_digest": "2dad9645a59bc81f2263ec4e0e2cd2f8d2996952ca7ea37f57c00f9948095c8c", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-animatednumber--playground&viewMode=story" }, { "id": "cloaked-design-system-primitives-animatednumber--count-up-on-change", "name": "Count Up On Change", "title": "Cloaked Design System/Primitives/AnimatedNumber", "exportName": "CountUpOnChange", "source_path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.stories.tsx", "source_digest": "2dad9645a59bc81f2263ec4e0e2cd2f8d2996952ca7ea37f57c00f9948095c8c", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-animatednumber--count-up-on-change&viewMode=story" }, { "id": "cloaked-design-system-primitives-animatednumber--formatted", "name": "Formatted", "title": "Cloaked Design System/Primitives/AnimatedNumber", "exportName": "Formatted", "source_path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.stories.tsx", "source_digest": "2dad9645a59bc81f2263ec4e0e2cd2f8d2996952ca7ea37f57c00f9948095c8c", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-animatednumber--formatted&viewMode=story" }, { "id": "cloaked-design-system-primitives-animatednumber--scrub-tracking", "name": "Scrub Tracking", "title": "Cloaked Design System/Primitives/AnimatedNumber", "exportName": "ScrubTracking", "source_path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.stories.tsx", "source_digest": "2dad9645a59bc81f2263ec4e0e2cd2f8d2996952ca7ea37f57c00f9948095c8c", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-animatednumber--scrub-tracking&viewMode=story" } ], "stories_source": { "path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.stories.tsx", "code": "import React from 'react';\nimport type { Meta, StoryObj } from '@storybook/react-vite';\nimport { Button } from '../Button/Button';\nimport { HStack } from '../../layout/HStack/HStack';\nimport { VStack } from '../../layout/VStack/VStack';\nimport { Text } from '../Text/Text';\nimport { disabledControl } from '../../../storybook/controlOptions';\nimport { AnimatedNumber } from './AnimatedNumber';\n\nconst meta: Meta = {\n title: 'Cloaked Design System/Primitives/AnimatedNumber',\n component: AnimatedNumber,\n parameters: {\n a11y: { test: 'error' },\n docs: {\n description: {\n component:\n 'A numeric readout that tweens from its old `value` to its new one on every change (physical ' +\n 'ease-in-out; never on mount; snaps under `prefers-reduced-motion`). It owns only motion + ' +\n 'formatting — wrap it in a `Text` (or `Card.Metric`) for typography and color. Set `follow` while a ' +\n 'chart is being scrubbed so per-move `value` updates glide instead of restarting each tween.',\n },\n },\n },\n args: {\n value: 1549,\n },\n argTypes: {\n value: {\n control: { type: 'number' },\n description: 'Target value; a change from the current display animates toward it.',\n },\n follow: {\n control: 'boolean',\n description:\n 'Per-frame glide toward `value` (for scrubbing) instead of a discrete tween. Ignores `duration`.',\n },\n duration: {\n control: { type: 'number' },\n description:\n 'Fixed tween ms for discrete changes. Omit to auto-scale with jump size. Ignored while `follow`.',\n },\n format: {\n ...disabledControl,\n description: 'Maps the number to a display string; defaults to locale digit grouping.',\n },\n },\n};\nexport default meta;\ntype Story = StoryObj;\n\nexport const Playground: Story = {\n render: args => (\n \n \n \n ),\n};\n\nfunction CountUpDemo() {\n const [value, setValue] = React.useState(1516);\n\n return (\n \n \n \n \n \n setValue(v => v + 137)}\n testId='animated-number-count-up-increment'\n >\n +137\n \n setValue(v => Math.max(0, v - 412))}\n testId='animated-number-count-up-decrement'\n >\n -412\n \n \n \n );\n}\n\nexport const CountUpOnChange: Story = {\n parameters: {\n docs: {\n description: {\n story: 'Discrete tween: each button press animates from the current value to the new total.',\n },\n },\n },\n render: () => ,\n};\n\nexport const Formatted: Story = {\n parameters: {\n docs: { description: { story: 'A custom `format` fn animates the raw number but renders it as currency.' } },\n },\n render: () => (\n \n \n n.toLocaleString('en-US', { style: 'currency', currency: 'USD', maximumFractionDigits: 0 })\n }\n />\n \n ),\n};\n\nconst SCRUB_VALUES = [241, 388, 612, 1102, 1549];\n\nfunction ScrubDemo() {\n const [index, setIndex] = React.useState(null);\n const shown = index == null ? 1549 : SCRUB_VALUES[index];\n\n return (\n \n \n {/* follow mode glides toward each selected bar while scrubbing; Release runs the momentum tick to total. */}\n \n \n \n {SCRUB_VALUES.map((v, i) => (\n setIndex(i)}\n testId={`animated-number-scrub-bar-${i + 1}`}\n >\n bar {i + 1}\n \n ))}\n setIndex(null)}\n testId='animated-number-scrub-release'\n >\n Release\n \n \n \n );\n}\n\nexport const ScrubTracking: Story = {\n parameters: {\n docs: {\n description: {\n story: '`follow` mode glides toward each tapped bar while scrubbing; Release settles to the total.',\n },\n },\n },\n render: () => ,\n};\n" }, "links": { "human": "/component-animatednumber", "json": "/data/components/animatednumber.json", "markdown": "/data/components/animatednumber.md", "storybook": "/storybook/?path=/story/cloaked-design-system-primitives-animatednumber--playground" }, "contract_status": "preview", "contract_kind": "source-derived", "approval": "required", "api": { "method": "typescript-type-checker", "typescript_version": "5.9.3", "public_export": "AnimatedNumber", "public_path": "AnimatedNumber", "import_path": "@cloakedinc/design-system", "root_kind": "component", "entrypoints": [ { "name": "AnimatedNumber", "signature": 1, "visibility": "public", "source": { "path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.tsx", "line": 51 }, "props_type": "AnimatedNumberProps", "props": [ { "name": "value", "type": "number", "declared_type": "number", "required": true, "description": "Target value to display; a change from the current value animates toward it.", "source": { "path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.tsx", "line": 20 } }, { "name": "follow", "type": "boolean | undefined", "declared_type": "boolean", "required": false, "description": "Continuously ease toward `value` every frame instead of running a fixed\ntween per change. Use this while a chart is being scrubbed: `value` changes\non every pointer move, and a per-change tween would restart faster than it\ncan advance (the number would freeze). Follow mode glides smoothly toward\nthe finger and settles when scrubbing stops.", "source": { "path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.tsx", "line": 28 }, "values": [ false, true ], "values_complete": true, "default": "false", "default_kind": "source-expression" }, { "name": "duration", "type": "number | undefined", "declared_type": "number", "required": false, "description": "Fixed tween duration in milliseconds for discrete changes. Omit to let the\nduration scale with how large the jump is, so small changes settle quickly\nand big ones feel weightier. Ignored while `follow` is true.", "source": { "path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.tsx", "line": 34 } }, { "name": "format", "type": "((value: number) => string) | undefined", "declared_type": "(value: number) => string", "required": false, "description": "Formats the numeric value for display; defaults to locale digit grouping.", "source": { "path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.tsx", "line": 36 }, "default": "formatNumber", "default_kind": "source-expression" }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Selector on the ``. Its text is a mid-animation frame; `aria-label` holds the settled value.", "source": { "path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.tsx", "line": 38 } } ], "branches": [], "constraints": [], "extraction_status": "extracted" } ], "type_sources": [ { "path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.tsx", "line": 18, "name": "AnimatedNumberProps", "code": "export interface AnimatedNumberProps {\n /** Target value to display; a change from the current value animates toward it. */\n value: number;\n /**\n * Continuously ease toward `value` every frame instead of running a fixed\n * tween per change. Use this while a chart is being scrubbed: `value` changes\n * on every pointer move, and a per-change tween would restart faster than it\n * can advance (the number would freeze). Follow mode glides smoothly toward\n * the finger and settles when scrubbing stops.\n */\n follow?: boolean;\n /**\n * Fixed tween duration in milliseconds for discrete changes. Omit to let the\n * duration scale with how large the jump is, so small changes settle quickly\n * and big ones feel weightier. Ignored while `follow` is true.\n */\n duration?: number;\n /** Formats the numeric value for display; defaults to locale digit grouping. */\n format?: (value: number) => string;\n /** Selector on the ``. Its text is a mid-animation frame; `aria-label` holds the settled value. */\n testId?: string;\n}" } ], "defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source." }, "platforms": { "implemented": [ "web" ], "native": "Imported design guidance only; no native implementation or parity verification in this preview.", "react": { "implementation": "local", "status": "preview", "parity": "web-reference" }, "vue": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "swift": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "kotlin": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" } }, "missing_facts": [ { "code": "human-review-pending", "detail": "This local preview has no recorded human design or engineering sign-off." }, { "code": "platform-parity-unverified", "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified." }, { "code": "figma-mapping-unverified", "detail": "No current component-level Figma node and immutable revision have been verified for this contract." } ], "review": { "local_status": "not-reviewed", "source_approval": null, "imported_spec_status": "approved", "spec_origin": "imported-adapted", "local_spec_source_status": "approved", "imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1", "note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract." } }