{ "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": "tabs", "name": "Tabs", "category": "Controls", "summary": "A horizontal tab list for choosing one sibling content panel, with a bold underline marking the controlled active tab.", "documentation": { "summary": "A horizontal tab list for choosing one sibling content panel, with a bold underline marking the controlled active tab.", "guidance": [ { "heading": "Overview", "body": "A horizontal tab strip (`role=\"tablist\"`) for switching between sibling content panels —\nOverview / Activity / Settings." }, { "heading": "When to use", "body": "Reach for `Tabs` when each option reveals a _different_ panel of content and you want them\nnavigable inline. It scales to more items than a `SegmentedControl`. In-app it splits the\nactivity views in `ActionsDetail`. The one it is most confused with is `SegmentedControl`: use that\ninstead when the options are a compact 2–4 value filter that re-slices a single view rather than\nswapping panels. Past ~5 tabs, prefer a picker over cramming the strip." }, { "heading": "Choosing a fit", "body": "`equal` divides the strip evenly and suits sets that fit the width, up to roughly five panels.\n`content` sizes each tab to its label and scrolls the strip horizontally, for sets that overflow\nthe equal fit — the underline tracks the active label's width instead of a computed column." } ], "usage": [], "examples": [], "source": "packages/design-system/src/components/controls/Tabs/Tabs.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/controls/Tabs/Tabs.tsx", "code": "import React, { useLayoutEffect, useRef } from 'react';\nimport { cn } from '../../../utilities';\nimport { useHaptic } from '../../../hooks/useHaptic';\nimport type { HapticFeedback } from '../../../tokens/CdsHaptic';\nimport styles from './Tabs.module.scss';\n\n/**\n * One tab. `id` is the selection key, the React key, and the default testId suffix, so it has to be\n * unique within the set.\n */\nexport interface TabItem {\n /** Matched against `activeId` and handed back by `onSelect`. Also the default test-selector suffix, so prefer kebab-case or set `testId`. */\n id: string;\n /** Visible tab text. Sizes the tab under the `content` fit; shares the strip under `equal`. */\n label: string;\n /** Overrides the id-derived test selector, for ids that are not kebab-case. */\n testId?: string;\n}\n\n/**\n * How tabs claim horizontal space. `equal` splits the strip between siblings; `content` sizes each\n * tab to its label and scrolls the strip, for sets too long to divide legibly.\n */\nexport type TabsFit = 'equal' | 'content';\n\n/**\n * Props for `Tabs`. Selection is controlled: the strip renders `activeId` as active and emits the\n * next id rather than tracking one.\n */\nexport interface TabsProps {\n /** Tabs in render order. Past roughly five, switch `fit` to `content` or use a picker. */\n items: TabItem[];\n /** Controlled `id` of the active tab. An id matching no item hides the underline entirely. */\n activeId: string;\n /** Called with the pressed tab's `id`. Never fires for the tab that is already active. */\n onSelect?: (id: string) => void;\n /** Accessible name for the tablist, such as `Dashboard sections`. */\n ariaLabel?: string;\n /** How tabs claim width. Defaults to `equal`. */\n fit?: TabsFit;\n className?: string;\n /** Haptic feedback for tab changes. Defaults to `true` (`selection`). */\n haptic?: HapticFeedback;\n /**\n * Selector for the strip, and the stem for each tab's own. Without it no tab gets a selector,\n * `TabItem.testId` included.\n */\n testId?: string;\n}\n\n/**\n * A horizontal tab strip for switching between sibling content panels. It renders the strip only —\n * `role='tablist'` promises panels, but wiring and showing them is the caller's. Reach for\n * `SegmentedControl` instead when the options re-filter one view rather than swapping panels.\n */\nexport function Tabs({\n items,\n activeId,\n onSelect,\n ariaLabel,\n fit = 'equal',\n className,\n haptic = true,\n testId,\n}: TabsProps) {\n const fireHaptic = useHaptic('selection');\n const stripRef = useRef(null);\n const isContentFit = fit === 'content';\n\n // Equal-width (flex: 1) tabs let the underline's offset be a pure function of the active\n // index, so selection slides as one bar in CSS instead of snapping a per-tab border. A stale\n // or empty activeId yields -1; we keep the underline hidden (via data-has-active) rather than\n // clamping it under the first tab while every button reads inactive.\n const activeIndex = items.findIndex(item => item.id === activeId);\n const hasActiveTab = activeIndex >= 0;\n // Depend on the ids rather than the array identity, so a consumer passing an inline literal\n // doesn't tear down and rebuild the observer below on every render. A label edit at the same\n // ids resizes the button, which the observer already catches.\n const itemsKey = items.map(item => item.id).join('|');\n const stripStyle = {\n '--tabs-count': items.length,\n '--tabs-active-index': hasActiveTab ? activeIndex : 0,\n } as React.CSSProperties;\n\n // Content-fit tabs are each as wide as their label, so the CSS column math above cannot place\n // the underline. Measure the active button instead. Scrolling here rather than in `onClick`\n // also covers mounting on a non-first tab and external `activeId` changes (routing, deep link).\n //\n // The strip is `overflow-x: auto`, so its box is sized by its parent and never reacts to content\n // growth — observing it alone would miss the label reflow this measurement exists for. Hence\n // observing every button, plus a re-measure once web fonts replace the fallback metrics. Every\n // button rather than only the active one, because a sibling that widens pushes the active tab\n // sideways: its `offsetLeft` goes stale without the active button itself ever resizing.\n useLayoutEffect(() => {\n const strip = stripRef.current;\n if (!isContentFit || !strip) return;\n\n const active = strip.querySelector('[data-tab-active=\"true\"]');\n\n // Revealing alongside the underline rather than only on mount: a font swap or a sibling\n // widening moves the active tab without resizing it, so the underline would track it out of\n // the strip's visible window and leave it clipped. A ResizeObserver never fires for a scroll,\n // so this cannot fight a manual scroll — only a real reflow re-reveals.\n const measure = () => {\n if (!active) return;\n strip.style.setProperty('--tabs-underline-left', `${active.offsetLeft}px`);\n strip.style.setProperty('--tabs-underline-width', `${active.offsetWidth}px`);\n revealActiveTab(strip, active);\n };\n\n measure();\n\n const observer = new ResizeObserver(measure);\n observer.observe(strip);\n strip.querySelectorAll('[role=\"tab\"]').forEach(tab => observer.observe(tab));\n\n let cancelled = false;\n document.fonts?.ready.then(() => {\n if (!cancelled) measure();\n });\n\n return () => {\n cancelled = true;\n observer.disconnect();\n };\n }, [isContentFit, activeId, itemsKey]);\n\n return (\n \n {items.map(item => {\n const isActive = item.id === activeId;\n\n return (\n {\n if (isActive) return;\n if (onSelect) fireHaptic(haptic);\n onSelect?.(item.id);\n }}\n data-testid={testId ? `${testId}-${item.testId ?? item.id}` : undefined}\n >\n {item.label}\n \n );\n })}\n \n );\n}\n\n/**\n * Reveals the active tab by scrolling the strip the minimum distance — `inline: 'nearest'` scoped to\n * this one scroller.\n *\n * Deliberately not `scrollIntoView`, which scrolls every scrollable ancestor and reasons in visual\n * coordinates: a router activity mounts already transformed off-screen, so the tab reads as invisible\n * and the browser scrolls an ancestor sideways, offsetting the panel for its whole transition.\n * `offsetLeft` is a layout coordinate, so this is immune to that transform.\n */\nfunction revealActiveTab(strip: HTMLElement, active: HTMLElement | null): void {\n if (!active) return;\n\n const left = active.offsetLeft;\n const right = left + active.offsetWidth;\n if (left < strip.scrollLeft) {\n strip.scrollLeft = left;\n } else if (right > strip.scrollLeft + strip.clientWidth) {\n strip.scrollLeft = right - strip.clientWidth;\n }\n}\n" }, "spec": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "Tabs", "status": "preview", "version": "1.1.1", "summary": "A horizontal tab list for choosing one sibling content panel, with a bold underline marking the controlled active tab." }, "parts": [ { "id": "tab-list", "label": "Tab list", "description": "Owns the accessible group name, horizontal spacing, divider, backdrop, and (content fit) horizontal scrolling." }, { "id": "tab", "label": "Tab", "description": "Native button exposing tab semantics and controlled selected state." }, { "id": "label", "label": "Tab label", "description": "Names the sibling content panel." }, { "id": "active-indicator", "label": "Active indicator", "description": "Bottom border marking the selected tab." } ], "allowedDesignChoices": { "variants": { "underline": { "label": "Underline", "description": "Horizontal text tabs with one bold bottom indicator." } }, "sizes": {}, "fits": { "equal": { "label": "Equal", "description": "Sibling tabs divide the strip evenly; use when the labels fit the width." }, "content": { "label": "Content", "description": "Each tab is as wide as its label and the strip scrolls horizontally; use for sets too long to divide legibly." } } }, "variants": [ { "id": "underline", "label": "Underline", "description": "Sibling tabs with one selected underline; equal-width by default, or content-sized and scrolling under the content fit.", "platforms": [ "ios", "android", "web" ] } ], "sizes": [], "measurements": [ { "id": "tab-gap", "label": "Equal-fit tab gap", "kind": "exact", "token": "--cds-space-24", "value": 24, "unit": "px", "appliesTo": [ "tab-list", "tab" ] }, { "id": "tab-list-horizontal-padding", "label": "Equal-fit tab-list horizontal padding", "kind": "exact", "token": "--cds-space-16", "value": 16, "unit": "px", "appliesTo": [ "tab-list" ] }, { "id": "tab-vertical-padding", "label": "Equal-fit tab vertical padding", "kind": "exact", "token": "--cds-space-12", "value": 12, "unit": "px", "appliesTo": [ "tab", "label", "active-indicator" ] }, { "id": "content-tab-horizontal-padding", "label": "Content-fit tab horizontal padding", "kind": "exact", "token": "--cds-space-20", "value": 20, "unit": "px", "appliesTo": [ "tab", "label" ] }, { "id": "content-tab-vertical-padding", "label": "Content-fit tab vertical padding", "kind": "exact", "token": "--cds-space-16", "value": 16, "unit": "px", "appliesTo": [ "tab", "label", "active-indicator" ] } ], "layout": { "alignment": "Equal-fit tabs share the available width; content-fit tabs size to their labels and scroll. Both center labels over the common bottom divider.", "flow": "Sibling tabs form one horizontal row with the active indicator attached to one tab.", "notes": [ "Reach for Tabs when each option reveals a different panel of content and you want them navigable inline; it scales to more items than a SegmentedControl.", "Use SegmentedControl instead when the options are a compact 2-4 value filter that re-slices a single view rather than swapping panels.", "Past ~5 tabs, prefer a picker over cramming the strip." ] }, "typographyAndColor": { "typography": [ { "label": "Tab label", "description": "Use the body ramp for primary navigation labels.", "token": "--cds-type-body-size" } ], "colors": [ { "label": "Tab label", "description": "Use primary text emphasis.", "token": "--cds-text-primary" }, { "label": "Divider", "description": "Use the semantic divider beneath the tab strip.", "token": "--cds-divider" }, { "label": "Active indicator", "description": "Use the bold semantic surface for the selected underline.", "token": "--cds-bg-bold" } ] }, "states": [ { "id": "inactive", "label": "Inactive", "description": "Shows a lower-emphasis label with selected false." }, { "id": "active", "label": "Active", "description": "Shows the active underline and selected true." }, { "id": "focused", "label": "Focused", "description": "Retains native button keyboard focus indication." } ], "behavior": [ { "label": "Controlled selection", "description": "Emit a tab id only when it differs from the controlled active id." }, { "label": "Panel ownership", "description": "Leave panel rendering and visibility to the integrating surface." }, { "label": "Sibling scope", "description": "Use tabs only for peer content destinations within the same surface." }, { "label": "Active tab reveal", "description": "When tabs are sized to their content, scroll the strip the minimum distance to bring the active tab into view — on mount, on external selection changes, and on any reflow that moves it (a font swap or a sibling widening), not only on press. Scroll the strip only; never scroll an enclosing scroll container, which would displace a surface that is mid-transition." } ], "accessibility": [ { "label": "Tab-list name", "description": "Provide a stable accessible name for the tab list." }, { "label": "Tab semantics", "description": "Expose every item as a tab with its selected state and visible label." }, { "label": "Panel relationship", "description": "The integrating surface should connect each tab to its owned tab panel when panels are rendered." } ], "contentAdaptation": [ { "label": "Tab count", "description": "Keep labels concise and the set at roughly five or fewer. Use the equal fit while the labels fit the width and the content fit once they overflow." }, { "label": "Parallel labels", "description": "Use concise peer nouns that describe the content panels." } ], "motionHaptics": { "motion": [ { "label": "Selection treatment", "description": "Move selection by updating underline and label emphasis without resizing the strip; the content fit also scrolls the newly selected tab into view." } ], "haptics": [ { "label": "Tab feedback", "description": "Request the selection haptic after the active tab changes." } ] }, "platformDifferences": [ { "platforms": [ "web" ], "description": "Tabs expose ARIA tab-list and tab roles while the integrating surface owns DOM tab panels and their relationships.", "rationale": "The reusable strip cannot know panel ids; native containers likewise connect the selected tab to platform-owned content." } ] }, "spec_source": "packages/design-system/src/components/controls/Tabs/Tabs.spec.json", "guidance_source": { "path": "packages/design-system/src/components/controls/Tabs/Tabs.mdx", "code": "import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';\nimport { ComponentSpec } from '../../../../.storybook/blocks';\nimport * as Stories from './Tabs.stories';\nimport tabsSpec from './Tabs.spec.json';\n\n\n\n# Tabs\n\nA horizontal tab strip (`role=\"tablist\"`) for switching between sibling content panels —\nOverview / Activity / Settings.\n\n\n\n## When to use\n\nReach for `Tabs` when each option reveals a _different_ panel of content and you want them\nnavigable inline. It scales to more items than a `SegmentedControl`. In-app it splits the\nactivity views in `ActionsDetail`. The one it is most confused with is `SegmentedControl`: use that\ninstead when the options are a compact 2–4 value filter that re-slices a single view rather than\nswapping panels. Past ~5 tabs, prefer a picker over cramming the strip.\n\n\n\n## Choosing a fit\n\n`equal` divides the strip evenly and suits sets that fit the width, up to roughly five panels.\n`content` sizes each tab to its label and scrolls the strip horizontally, for sets that overflow\nthe equal fit — the underline tracks the active label's width instead of a computed column.\n\n\n\n## Design Guidelines\n\n\n\n## Props\n\n\n" }, "props": [ { "name": "items", "type": "TabItem[]", "declared_type": "TabItem[]", "required": true, "description": "Tabs in render order. Past roughly five, switch `fit` to `content` or use a picker.", "source": { "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx", "line": 32 } }, { "name": "activeId", "type": "string", "declared_type": "string", "required": true, "description": "Controlled `id` of the active tab. An id matching no item hides the underline entirely.", "source": { "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx", "line": 34 } }, { "name": "onSelect", "type": "((id: string) => void) | undefined", "declared_type": "(id: string) => void", "required": false, "description": "Called with the pressed tab's `id`. Never fires for the tab that is already active.", "source": { "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx", "line": 36 } }, { "name": "ariaLabel", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Accessible name for the tablist, such as `Dashboard sections`.", "source": { "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx", "line": 38 } }, { "name": "fit", "type": "TabsFit | undefined", "declared_type": "TabsFit", "required": false, "description": "How tabs claim width. Defaults to `equal`.", "source": { "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx", "line": 40 }, "values": [ "content", "equal" ], "values_complete": true, "default": "'equal'", "default_kind": "source-expression" }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx", "line": 41 } }, { "name": "haptic", "type": "HapticFeedback | undefined", "declared_type": "HapticFeedback", "required": false, "description": "Haptic feedback for tab changes. Defaults to `true` (`selection`).", "source": { "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx", "line": 43 }, "values": [ "error", "heavy", "light", "medium", "selection", "success", "warning", false, true ], "values_complete": true, "default": "true", "default_kind": "source-expression" }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Selector for the strip, and the stem for each tab's own. Without it no tab gets a selector,\n`TabItem.testId` included.", "source": { "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx", "line": 48 } } ], "prop_shapes": {}, "examples": [], "tokens": [ { "name": "--cds-space-24", "light": "24px", "dark": "24px" }, { "name": "--cds-space-16", "light": "16px", "dark": "16px" }, { "name": "--cds-space-12", "light": "12px", "dark": "12px" }, { "name": "--cds-space-20", "light": "20px", "dark": "20px" }, { "name": "--cds-type-body-size", "light": "1rem", "dark": "1rem" }, { "name": "--cds-text-primary", "light": "#141410", "dark": "#f3f1ed" }, { "name": "--cds-divider", "light": "#e0ddd6", "dark": "#ffffff1a" }, { "name": "--cds-bg-bold", "light": "#0b0b0a", "dark": "#ffffff" } ], "visual_reference": { "stories": [ { "id": "cloaked-design-system-controls-tabs--playground", "name": "Playground", "title": "Cloaked Design System/Controls/Tabs", "exportName": "Playground", "source_path": "packages/design-system/src/components/controls/Tabs/Tabs.stories.tsx", "source_digest": "0a4d706dd01767646572bf5f44544c15490f9ffde1d2baaee64fba9528fac41f", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-controls-tabs--playground&viewMode=story" }, { "id": "cloaked-design-system-controls-tabs--middle-active", "name": "Middle Active", "title": "Cloaked Design System/Controls/Tabs", "exportName": "MiddleActive", "source_path": "packages/design-system/src/components/controls/Tabs/Tabs.stories.tsx", "source_digest": "0a4d706dd01767646572bf5f44544c15490f9ffde1d2baaee64fba9528fac41f", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-controls-tabs--middle-active&viewMode=story" }, { "id": "cloaked-design-system-controls-tabs--many-tabs", "name": "Many Tabs", "title": "Cloaked Design System/Controls/Tabs", "exportName": "ManyTabs", "source_path": "packages/design-system/src/components/controls/Tabs/Tabs.stories.tsx", "source_digest": "0a4d706dd01767646572bf5f44544c15490f9ffde1d2baaee64fba9528fac41f", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-controls-tabs--many-tabs&viewMode=story" }, { "id": "cloaked-design-system-controls-tabs--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Controls/Tabs", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/controls/Tabs/Tabs.stories.tsx", "source_digest": "0a4d706dd01767646572bf5f44544c15490f9ffde1d2baaee64fba9528fac41f", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-controls-tabs--dark-theme&viewMode=story" }, { "id": "cloaked-design-system-controls-tabs--content-fit", "name": "Content Fit", "title": "Cloaked Design System/Controls/Tabs", "exportName": "ContentFit", "source_path": "packages/design-system/src/components/controls/Tabs/Tabs.stories.tsx", "source_digest": "0a4d706dd01767646572bf5f44544c15490f9ffde1d2baaee64fba9528fac41f", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-controls-tabs--content-fit&viewMode=story" } ], "name": "Tabs", "id": "tabs", "category": "Controls" }, "stories": [ { "id": "cloaked-design-system-controls-tabs--playground", "name": "Playground", "title": "Cloaked Design System/Controls/Tabs", "exportName": "Playground", "source_path": "packages/design-system/src/components/controls/Tabs/Tabs.stories.tsx", "source_digest": "0a4d706dd01767646572bf5f44544c15490f9ffde1d2baaee64fba9528fac41f", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-controls-tabs--playground&viewMode=story" }, { "id": "cloaked-design-system-controls-tabs--middle-active", "name": "Middle Active", "title": "Cloaked Design System/Controls/Tabs", "exportName": "MiddleActive", "source_path": "packages/design-system/src/components/controls/Tabs/Tabs.stories.tsx", "source_digest": "0a4d706dd01767646572bf5f44544c15490f9ffde1d2baaee64fba9528fac41f", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-controls-tabs--middle-active&viewMode=story" }, { "id": "cloaked-design-system-controls-tabs--many-tabs", "name": "Many Tabs", "title": "Cloaked Design System/Controls/Tabs", "exportName": "ManyTabs", "source_path": "packages/design-system/src/components/controls/Tabs/Tabs.stories.tsx", "source_digest": "0a4d706dd01767646572bf5f44544c15490f9ffde1d2baaee64fba9528fac41f", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-controls-tabs--many-tabs&viewMode=story" }, { "id": "cloaked-design-system-controls-tabs--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Controls/Tabs", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/controls/Tabs/Tabs.stories.tsx", "source_digest": "0a4d706dd01767646572bf5f44544c15490f9ffde1d2baaee64fba9528fac41f", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-controls-tabs--dark-theme&viewMode=story" }, { "id": "cloaked-design-system-controls-tabs--content-fit", "name": "Content Fit", "title": "Cloaked Design System/Controls/Tabs", "exportName": "ContentFit", "source_path": "packages/design-system/src/components/controls/Tabs/Tabs.stories.tsx", "source_digest": "0a4d706dd01767646572bf5f44544c15490f9ffde1d2baaee64fba9528fac41f", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-controls-tabs--content-fit&viewMode=story" } ], "stories_source": { "path": "packages/design-system/src/components/controls/Tabs/Tabs.stories.tsx", "code": "import React, { useState } from 'react';\nimport type { Meta, StoryObj } from '@storybook/react-vite';\nimport { disabledControl, hapticArgType } from '../../../storybook/controlOptions';\nimport { Tabs, type TabItem } from './Tabs';\n\nconst THREE_ITEMS: TabItem[] = [\n { id: 'all', label: 'All' },\n { id: 'monitoring', label: 'Monitoring' },\n { id: 'guard', label: 'Guard' },\n];\n\nconst FIVE_ITEMS: TabItem[] = [\n { id: 'overview', label: 'Overview' },\n { id: 'activity', label: 'Activity' },\n { id: 'settings', label: 'Settings' },\n { id: 'members', label: 'Members' },\n { id: 'billing', label: 'Billing' },\n];\n\nconst meta: Meta = {\n title: 'Cloaked Design System/Controls/Tabs',\n component: Tabs,\n parameters: {\n a11y: { test: 'error' },\n docs: {\n description: {\n component:\n 'A horizontal tab strip (role tablist) for switching between sibling content panels — ' +\n 'Overview / Activity / Settings. Scales to more items than a `SegmentedControl`, which is the ' +\n 'right choice for a compact 2–4 option switch that re-filters one view rather than swapping ' +\n 'panels.',\n },\n },\n },\n args: {\n items: THREE_ITEMS,\n activeId: 'all',\n ariaLabel: 'Dashboard sections',\n testId: 'controls-tabs',\n },\n argTypes: {\n items: { ...disabledControl, description: 'Tabs rendered in order; each is a `TabItem`.' },\n activeId: { control: 'text', description: 'Controlled: `id` of the selected tab.' },\n onSelect: { ...disabledControl, description: 'Called with the selected tab `id`.' },\n ariaLabel: { control: 'text', description: 'Accessible name for the tablist.' },\n haptic: {\n ...hapticArgType,\n description: 'Haptic on tab change. Defaults to `true` (`selection`).',\n },\n },\n};\nexport default meta;\ntype Story = StoryObj;\n\nfunction TabsPlayground() {\n const [activeId, setActiveId] = useState(THREE_ITEMS[0].id);\n\n return (\n \n );\n}\n\nexport const Playground: Story = {\n parameters: { docs: { description: { story: 'Interactive — `onSelect` drives `activeId` through React state.' } } },\n render: () => ,\n};\n\nexport const MiddleActive: Story = {\n args: { activeId: 'monitoring' },\n parameters: { docs: { description: { story: 'A non-first tab selected.' } } },\n};\n\nexport const ManyTabs: Story = {\n args: { items: FIVE_ITEMS, activeId: 'settings' },\n parameters: {\n docs: { description: { story: 'Five tabs — beyond this, prefer a picker over cramming the strip.' } },\n },\n};\n\nexport const DarkTheme: Story = {\n globals: { theme: 'dark' },\n parameters: { docs: { description: { story: 'Tab strip on the dark theme surface.' } } },\n};\n\n// Ids mirror a real consumer's camelCase domain keys; `testId` keeps the derived selectors\n// kebab-case.\nconst CONTENT_FIT_ITEMS: TabItem[] = [\n { id: 'popular', label: 'Most popular' },\n { id: 'riskiest', label: 'Worst offenders' },\n { id: 'safest', label: 'Safer picks' },\n { id: 'sellsData', label: 'Sells your data', testId: 'sells-data' },\n { id: 'recentlyBreached', label: 'Recently breached', testId: 'recently-breached' },\n];\n\nfunction ContentFitPlayground() {\n const [activeId, setActiveId] = useState(CONTENT_FIT_ITEMS[0].id);\n\n return (\n \n );\n}\n\nexport const ContentFit: Story = {\n parameters: {\n docs: {\n description: {\n story:\n 'Interactive — each tab sizes to its label and the strip scrolls; selecting a tab tracks ' +\n 'the underline to the new label and scrolls it into view instead of resizing a computed ' +\n 'column width.',\n },\n },\n },\n render: () => ,\n};\n" }, "links": { "human": "/component-tabs", "json": "/data/components/tabs.json", "markdown": "/data/components/tabs.md", "storybook": "/storybook/?path=/story/cloaked-design-system-controls-tabs--playground" }, "contract_status": "preview", "contract_kind": "source-derived", "approval": "required", "api": { "method": "typescript-type-checker", "typescript_version": "5.9.3", "public_export": "Tabs", "public_path": "Tabs", "import_path": "@cloakedinc/design-system", "root_kind": "component", "entrypoints": [ { "name": "Tabs", "signature": 1, "visibility": "public", "source": { "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx", "line": 56 }, "props_type": "TabsProps", "props": [ { "name": "items", "type": "TabItem[]", "declared_type": "TabItem[]", "required": true, "description": "Tabs in render order. Past roughly five, switch `fit` to `content` or use a picker.", "source": { "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx", "line": 32 } }, { "name": "activeId", "type": "string", "declared_type": "string", "required": true, "description": "Controlled `id` of the active tab. An id matching no item hides the underline entirely.", "source": { "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx", "line": 34 } }, { "name": "onSelect", "type": "((id: string) => void) | undefined", "declared_type": "(id: string) => void", "required": false, "description": "Called with the pressed tab's `id`. Never fires for the tab that is already active.", "source": { "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx", "line": 36 } }, { "name": "ariaLabel", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Accessible name for the tablist, such as `Dashboard sections`.", "source": { "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx", "line": 38 } }, { "name": "fit", "type": "TabsFit | undefined", "declared_type": "TabsFit", "required": false, "description": "How tabs claim width. Defaults to `equal`.", "source": { "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx", "line": 40 }, "values": [ "content", "equal" ], "values_complete": true, "default": "'equal'", "default_kind": "source-expression" }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx", "line": 41 } }, { "name": "haptic", "type": "HapticFeedback | undefined", "declared_type": "HapticFeedback", "required": false, "description": "Haptic feedback for tab changes. Defaults to `true` (`selection`).", "source": { "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx", "line": 43 }, "values": [ "error", "heavy", "light", "medium", "selection", "success", "warning", false, true ], "values_complete": true, "default": "true", "default_kind": "source-expression" }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Selector for the strip, and the stem for each tab's own. Without it no tab gets a selector,\n`TabItem.testId` included.", "source": { "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx", "line": 48 } } ], "branches": [], "constraints": [], "extraction_status": "extracted" } ], "type_sources": [ { "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx", "line": 11, "name": "TabItem", "code": "export interface TabItem {\n /** Matched against `activeId` and handed back by `onSelect`. Also the default test-selector suffix, so prefer kebab-case or set `testId`. */\n id: string;\n /** Visible tab text. Sizes the tab under the `content` fit; shares the strip under `equal`. */\n label: string;\n /** Overrides the id-derived test selector, for ids that are not kebab-case. */\n testId?: string;\n}" }, { "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx", "line": 24, "name": "TabsFit", "code": "export type TabsFit = 'equal' | 'content';" }, { "path": "packages/design-system/src/components/controls/Tabs/Tabs.tsx", "line": 30, "name": "TabsProps", "code": "export interface TabsProps {\n /** Tabs in render order. Past roughly five, switch `fit` to `content` or use a picker. */\n items: TabItem[];\n /** Controlled `id` of the active tab. An id matching no item hides the underline entirely. */\n activeId: string;\n /** Called with the pressed tab's `id`. Never fires for the tab that is already active. */\n onSelect?: (id: string) => void;\n /** Accessible name for the tablist, such as `Dashboard sections`. */\n ariaLabel?: string;\n /** How tabs claim width. Defaults to `equal`. */\n fit?: TabsFit;\n className?: string;\n /** Haptic feedback for tab changes. Defaults to `true` (`selection`). */\n haptic?: HapticFeedback;\n /**\n * Selector for the strip, and the stem for each tab's own. Without it no tab gets a selector,\n * `TabItem.testId` included.\n */\n testId?: string;\n}" }, { "path": "packages/design-system/src/tokens/CdsHaptic.ts", "line": 6, "name": "HapticFeedback", "code": "export type HapticFeedback = boolean | HapticType;" }, { "path": "packages/design-system/src/tokens/HapticType.ts", "line": 2, "name": "HapticType", "code": "export type HapticType = 'light' | 'medium' | 'heavy' | 'success' | 'warning' | 'error' | 'selection';" } ], "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." } }