@usefragments/ui 1.0.0

package/src/components/Tabs/Tabs.module.scss

@@ -0,0 +1,179 @@
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+
+// Root container
+.root {
+  display: flex;
+  flex-direction: column;
+  font-family: var(--fui-font-sans, $fui-font-sans);
+
+  &[data-orientation="vertical"] {
+    flex-direction: row;
+  }
+}
+
+// Tab list container
+.list {
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-1, $fui-space-1);
+  border-bottom: 1px solid var(--fui-border, $fui-border);
+  padding: 0 var(--fui-space-1, $fui-space-1);
+
+  &[data-orientation="vertical"] {
+    flex-direction: column;
+    align-items: stretch;
+    border-bottom: none;
+    border-right: 1px solid var(--fui-border, $fui-border);
+    padding: var(--fui-space-1, $fui-space-1) 0;
+  }
+}
+
+// Variant: pills (shadcn-style with background container)
+.listPills {
+  border-bottom: none;
+  border: 0;
+  background-color: var(
+    --fui-tabs-pills-bg,
+    color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 5%, transparent)
+  );
+  border-radius: var(--fui-radius-lg, $fui-radius-lg);
+  padding: 0;
+  gap: 0;
+  box-shadow: inset 0 0 0 1px
+    var(
+      --fui-tabs-pills-border,
+      color-mix(in srgb, var(--fui-border, #{$fui-border}) 72%, transparent)
+    );
+  width: fit-content;
+}
+
+// Variant: underline (default, with indicator line)
+.listUnderline {
+  // Default styles already applied to .list
+}
+
+// Individual tab button
+.tab {
+  @include button-reset;
+  @include interactive-base;
+
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--fui-space-2, $fui-space-2);
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  white-space: nowrap;
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
+
+  &:hover:not([data-disabled]) {
+    color: var(--fui-text-primary, $fui-text-primary);
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+  }
+
+  &[data-active] {
+    color: var(--fui-text-primary, $fui-text-primary);
+  }
+
+  &[data-disabled] {
+    color: var(--fui-text-tertiary, $fui-text-tertiary);
+  }
+}
+
+.tabSm {
+  min-height: var(--fui-button-height-sm, $fui-button-height-sm);
+  padding: 0 var(--fui-space-2, $fui-space-2);
+}
+
+.tabMd {
+  min-height: var(--fui-button-height-md, $fui-button-height-md);
+  padding: 0 var(--fui-space-3, $fui-space-3);
+}
+
+.tabLg {
+  min-height: var(--fui-button-height-lg, $fui-button-height-lg);
+  padding: 0 var(--fui-space-4, $fui-space-4);
+  font-size: var(--fui-font-size-base, $fui-font-size-base);
+}
+
+// Tab in underline variant
+.tabUnderline {
+  border-radius: 0;
+  margin-bottom: -1px;
+
+  &:hover:not([data-disabled]) {
+    background-color: transparent;
+  }
+}
+
+// Tab in pills variant (shadcn-style)
+.tabPills {
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+  transition:
+    background-color var(--fui-transition-fast, $fui-transition-fast),
+    color var(--fui-transition-fast, $fui-transition-fast),
+    box-shadow var(--fui-transition-fast, $fui-transition-fast);
+
+  &:hover:not([data-disabled]):not([data-active]) {
+    background-color: var(--fui-tabs-pill-hover-bg, transparent);
+    color: var(--fui-text-primary, $fui-text-primary);
+  }
+
+  &[data-active] {
+    background-color: var(--fui-tabs-pill-active-bg, var(--fui-bg-elevated, #{$fui-bg-elevated}));
+    color: var(--fui-text-primary, $fui-text-primary);
+    box-shadow: var(--fui-tabs-pill-active-shadow, none);
+  }
+}
+
+// Animated indicator (underline variant)
+.indicator {
+  position: absolute;
+  bottom: 0;
+  left: 0;
+  height: 2px;
+  background-color: var(--fui-color-accent, $fui-color-accent);
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+
+  // Use CSS variables from Base UI for position
+  width: var(--active-tab-width);
+  transform: translateX(var(--active-tab-left));
+  transition:
+    width var(--fui-transition-fast, $fui-transition-fast),
+    transform var(--fui-transition-fast, $fui-transition-fast);
+
+  [data-orientation="vertical"] & {
+    bottom: auto;
+    left: auto;
+    right: 0;
+    top: 0;
+    width: 2px;
+    height: var(--active-tab-height);
+    transform: translateY(var(--active-tab-top));
+  }
+}
+
+// Tab panel content
+.panel {
+  padding: var(--fui-space-2, $fui-space-2) 0;
+  outline: none;
+
+  &[data-hidden] {
+    display: none;
+  }
+
+  // Focus visible for keyboard navigation
+  &:focus-visible {
+    @include focus-ring;
+    border-radius: var(--fui-radius-md, $fui-radius-md);
+  }
+}
+
+// Panel with no padding (for custom layouts)
+.panelFlush {
+  padding: 0;
+}

package/src/components/Tabs/Tabs.stories.tsx

@@ -0,0 +1,136 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Tabs } from '.';
+
+/**
+ * Tabs is the canonical content-switcher primitive. Use it to organize related
+ * content into navigable panels — agents should compose
+ * `Tabs.List`/`Tabs.Tab`/`Tabs.Panel` rather than hand-rolling a tab control
+ * with manual focus management.
+ */
+const meta = {
+  title: 'Navigation/Tabs',
+  component: Tabs,
+  tags: ['autodocs', 'canonical'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Organize content into switchable panels following the WAI-ARIA tabs pattern. Prefer this over a hand-rolled tab control.',
+      },
+    },
+  },
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['underline', 'pills'],
+      description: 'Default visual style for Tabs.List',
+    },
+    orientation: {
+      control: 'select',
+      options: ['horizontal', 'vertical'],
+      description: 'Tab list orientation',
+    },
+  },
+  args: {
+    variant: 'underline',
+    orientation: 'horizontal',
+    defaultValue: 'overview',
+    children: (
+      <>
+        <Tabs.List>
+          <Tabs.Tab value="overview">Overview</Tabs.Tab>
+          <Tabs.Tab value="analytics">Analytics</Tabs.Tab>
+        </Tabs.List>
+        <Tabs.Panel value="overview">
+          <p>Overview content goes here.</p>
+        </Tabs.Panel>
+        <Tabs.Panel value="analytics">
+          <p>Analytics content goes here.</p>
+        </Tabs.Panel>
+      </>
+    ),
+  },
+} satisfies Meta<typeof Tabs>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Underline: Story = {
+  render: () => (
+    <Tabs defaultValue="overview" variant="underline">
+      <Tabs.List>
+        <Tabs.Tab value="overview">Overview</Tabs.Tab>
+        <Tabs.Tab value="analytics">Analytics</Tabs.Tab>
+        <Tabs.Tab value="settings">Settings</Tabs.Tab>
+      </Tabs.List>
+      <Tabs.Panel value="overview">
+        <p>Overview content goes here.</p>
+      </Tabs.Panel>
+      <Tabs.Panel value="analytics">
+        <p>Analytics content goes here.</p>
+      </Tabs.Panel>
+      <Tabs.Panel value="settings">
+        <p>Settings content goes here.</p>
+      </Tabs.Panel>
+    </Tabs>
+  ),
+};
+
+export const Pills: Story = {
+  render: () => (
+    <Tabs defaultValue="all" variant="pills">
+      <Tabs.List>
+        <Tabs.Tab value="all">All</Tabs.Tab>
+        <Tabs.Tab value="active">Active</Tabs.Tab>
+        <Tabs.Tab value="archived">Archived</Tabs.Tab>
+      </Tabs.List>
+      <Tabs.Panel value="all">
+        <p>Showing all items.</p>
+      </Tabs.Panel>
+      <Tabs.Panel value="active">
+        <p>Showing active items only.</p>
+      </Tabs.Panel>
+      <Tabs.Panel value="archived">
+        <p>Showing archived items.</p>
+      </Tabs.Panel>
+    </Tabs>
+  ),
+};
+
+export const WithDisabled: Story = {
+  render: () => (
+    <Tabs defaultValue="general" variant="underline">
+      <Tabs.List>
+        <Tabs.Tab value="general">General</Tabs.Tab>
+        <Tabs.Tab value="security">Security</Tabs.Tab>
+        <Tabs.Tab value="billing" disabled>
+          Billing
+        </Tabs.Tab>
+      </Tabs.List>
+      <Tabs.Panel value="general">
+        <p>General settings panel.</p>
+      </Tabs.Panel>
+      <Tabs.Panel value="security">
+        <p>Security settings panel.</p>
+      </Tabs.Panel>
+    </Tabs>
+  ),
+};
+
+export const ListVariantOverride: Story = {
+  render: () => (
+    <Tabs defaultValue="overview" variant="pills">
+      <Tabs.List variant="underline">
+        <Tabs.Tab value="overview">Overview</Tabs.Tab>
+        <Tabs.Tab value="activity">Activity</Tabs.Tab>
+      </Tabs.List>
+      <Tabs.Panel value="overview">
+        <p>Root sets pills, but this list overrides to underline.</p>
+      </Tabs.Panel>
+      <Tabs.Panel value="activity">
+        <p>Per-list variant override example.</p>
+      </Tabs.Panel>
+    </Tabs>
+  ),
+};

package/src/components/Tabs/index.tsx

@@ -0,0 +1,168 @@
+"use client";
+
+import * as React from "react";
+import { Tabs as BaseTabs } from "@base-ui/react/tabs";
+import { useResolvedControlSize, type ControlSize } from "../ComponentDefaults";
+import styles from "./Tabs.module.scss";
+
+// ============================================
+// Types
+// ============================================
+
+export type TabValue = string;
+export type TabsChangeEventDetails = Parameters<
+  NonNullable<React.ComponentProps<typeof BaseTabs.Root>["onValueChange"]>
+>[1];
+
+/**
+ * Tabbed navigation for switching between content panels.
+ * @see https://usefragments.com/components/tabs
+ */
+export interface TabsProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "defaultValue"> {
+  children: React.ReactNode;
+  /** Default active tab value (uncontrolled) */
+  defaultValue?: TabValue;
+  /** Controlled active tab value */
+  value?: TabValue;
+  /** Called when the active tab changes */
+  onValueChange?: (value: TabValue, eventDetails: TabsChangeEventDetails) => void;
+  /** Tab layout direction.
+   * @default "horizontal" */
+  orientation?: "horizontal" | "vertical";
+  /** Tab list visual style (default for Tabs.List).
+   * @default "underline" */
+  variant?: "underline" | "pills";
+  /** Tab control size. Defaults to the component-default control size. */
+  size?: ControlSize;
+}
+
+export interface TabsListProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+  /** Tab list visual style.
+   * @default "underline"
+   * @see https://usefragments.com/components/tabs#variants */
+  variant?: "underline" | "pills";
+  /** Tab control size. Defaults to the nearest Tabs root or provider default. */
+  size?: ControlSize;
+}
+
+export interface TabProps {
+  children: React.ReactNode;
+  value: TabValue;
+  disabled?: boolean;
+  className?: string;
+}
+
+export interface TabsPanelProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+  value: TabValue;
+  keepMounted?: boolean;
+  flush?: boolean;
+}
+
+// ============================================
+// Context for variant
+// ============================================
+
+const TabsVariantContext = React.createContext<"underline" | "pills">("underline");
+const TabsSizeContext = React.createContext<ControlSize>("sm");
+
+// ============================================
+// Components
+// ============================================
+
+function TabsRoot({
+  children,
+  defaultValue,
+  value,
+  onValueChange,
+  orientation = "horizontal",
+  variant = "underline",
+  size: sizeProp,
+  className,
+  ...htmlProps
+}: TabsProps) {
+  const size = useResolvedControlSize(sizeProp, "sm");
+  const classes = [styles.root, className].filter(Boolean).join(" ");
+
+  return (
+    <TabsVariantContext.Provider value={variant}>
+      <TabsSizeContext.Provider value={size}>
+        <BaseTabs.Root
+          {...htmlProps}
+          defaultValue={defaultValue}
+          value={value}
+          onValueChange={onValueChange}
+          orientation={orientation}
+          className={classes}
+        >
+          {children}
+        </BaseTabs.Root>
+      </TabsSizeContext.Provider>
+    </TabsVariantContext.Provider>
+  );
+}
+
+function TabsList({ children, variant, size: sizeProp, className, ...htmlProps }: TabsListProps) {
+  const rootVariant = React.useContext(TabsVariantContext);
+  const rootSize = React.useContext(TabsSizeContext);
+  const size = sizeProp ?? rootSize;
+  const resolvedVariant = variant ?? rootVariant;
+  const variantClass = resolvedVariant === "pills" ? styles.listPills : styles.listUnderline;
+  const classes = [styles.list, variantClass, className].filter(Boolean).join(" ");
+
+  return (
+    <TabsVariantContext.Provider value={resolvedVariant}>
+      <TabsSizeContext.Provider value={size}>
+        <BaseTabs.List {...htmlProps} className={classes}>
+          {children}
+          {resolvedVariant === "underline" && <BaseTabs.Indicator className={styles.indicator} />}
+        </BaseTabs.List>
+      </TabsSizeContext.Provider>
+    </TabsVariantContext.Provider>
+  );
+}
+
+function Tab({ children, value, disabled, className }: TabProps) {
+  const variant = React.useContext(TabsVariantContext);
+  const size = React.useContext(TabsSizeContext);
+  const variantClass = variant === "pills" ? styles.tabPills : styles.tabUnderline;
+  const sizeClass = size === "sm" ? styles.tabSm : size === "lg" ? styles.tabLg : styles.tabMd;
+  const classes = [styles.tab, sizeClass, variantClass, className].filter(Boolean).join(" ");
+
+  return (
+    <BaseTabs.Tab value={value} disabled={disabled} className={classes}>
+      {children}
+    </BaseTabs.Tab>
+  );
+}
+
+function TabsPanel({
+  children,
+  value,
+  keepMounted = false,
+  flush = false,
+  className,
+  ...htmlProps
+}: TabsPanelProps) {
+  const classes = [styles.panel, flush && styles.panelFlush, className].filter(Boolean).join(" ");
+
+  return (
+    <BaseTabs.Panel {...htmlProps} value={value} keepMounted={keepMounted} className={classes}>
+      {children}
+    </BaseTabs.Panel>
+  );
+}
+
+// ============================================
+// Export compound component
+// ============================================
+
+export const Tabs = Object.assign(TabsRoot, {
+  List: TabsList,
+  Tab: Tab,
+  Panel: TabsPanel,
+});
+
+// Re-export individual components
+export { TabsRoot, TabsList, Tab, TabsPanel };