@newtonedev/components 0.1.6 → 0.1.8

package/src/primitives/Text/Text.tsx

@@ -1,16 +1,32 @@
-import React, { useMemo } from 'react';
-import { Text as RNText } from 'react-native';
-import type { TextStyle } from 'react-native';
+import React, { createContext, useMemo, useState, useEffect } from 'react';
+import { Text as RNText, View } from 'react-native';
+import type { LayoutChangeEvent, TextStyle } from 'react-native';
 import { srgbToHex } from 'newtone';
+import { resolveResponsiveSize, estimateLineWidths, BREAKPOINT_ROLE_SCALE, scaleRoleStep, REFERENCE_LINE_HEIGHT_RATIO, buildFontFeatureSettings, SEMANTIC_WEIGHT_MAP, ROLE_DEFAULT_WEIGHTS } from '@newtonedev/fonts';
 import { useTokens } from '../../tokens/useTokens';
+import { useNewtoneTheme } from '../../theme/NewtoneProvider';
 import type { UseTokensResult } from '../../tokens/useTokens';
 import type { TextProps, TextColor } from './Text.types';
+import { useLocalCalibration } from '../../fonts/useLocalCalibration';
+import { useTypographyCalibrations } from '../../fonts/useTypographyCalibrations';
+import { enqueueObservation } from '../../fonts/reportQueue';
+import { useBreakpoint } from '../../theme/useBreakpoint';
+
+/**
+ * Context to pass the active scope's weight map to span sub-components.
+ * Spans inherit font family from the parent RN Text, but need the scope's
+ * weight mapping to resolve semantic weight tokens (regular/medium/bold)
+ * to numeric CSS values.
+ */
+export const TextScopeContext = createContext<{
+  readonly weights: { readonly regular: number; readonly medium: number; readonly bold: number };
+} | null>(null);
 
 /**
  * Resolve a semantic text color to a hex string from the current tokens.
  * Neutral text colors are top-level; palette colors use nested PaletteTokens.fill.
  */
-function resolveTextColor(color: TextColor, tokens: UseTokensResult): string {
+export function resolveTextColor(color: TextColor, tokens: UseTokensResult): string {
   switch (color) {
     case 'primary': return srgbToHex(tokens.textPrimary.srgb);
     case 'secondary': return srgbToHex(tokens.textSecondary.srgb);
@@ -23,78 +39,214 @@ function resolveTextColor(color: TextColor, tokens: UseTokensResult): string {
   }
 }
 
+/** Adaptive roles that support responsive font sizing. */
+const ADAPTIVE_ROLES = new Set(['headline', 'title', 'heading', 'subheading']);
+
+/** Maps heading-like roles to HTML heading levels for semantic rendering on web. */
+const ROLE_HEADING_LEVEL: Readonly<Record<string, number>> = {
+  headline: 1,
+  title: 2,
+  heading: 3,
+};
+
+/** Estimate total character count from potentially nested React children. */
+function extractCharacterCount(node: React.ReactNode): number {
+  if (typeof node === 'string') return node.length;
+  if (typeof node === 'number') return String(node).length;
+  if (!node) return 0;
+  if (Array.isArray(node)) {
+    return node.reduce((sum: number, child) => sum + extractCharacterCount(child), 0);
+  }
+  if (typeof node === 'object' && 'props' in node) {
+    return extractCharacterCount((node as React.ReactElement).props?.children);
+  }
+  return 0;
+}
+
 /**
- * Token-aware text primitive.
+ * Token-aware text primitive with semantic scope + role API.
  *
- * Reads typography tokens from the nearest NewtoneProvider and maps
- * semantic props (size, weight, color, font, lineHeight) to resolved values.
+ * - `scope` selects the font family (main, display, mono, currency)
+ * - `role` sets default weight; fontSize and lineHeight resolved from config's role mapping
+ * - `size` selects within the role's 3-step scale (sm, md, lg)
+ * - `responsive` enables container-width-aware font sizing for adaptive roles
  *
  * @example
  * ```tsx
- * <Text>Body text</Text>
- * <Text size="sm" weight="semibold" color="secondary">Label</Text>
- * <Text size="xl" font="display">Heading</Text>
+ * <Text>Body text (default)</Text>
+ * <Text role="headline" scope="display">Hero title</Text>
+ * <Text role="label">Form label</Text>
+ * <Text scope="mono" role="caption">const x = 42;</Text>
+ * <Text role="body">Regular <Text.Bold>bold</Text.Bold> text</Text>
+ * <Text role="headline" responsive>Responsive headline</Text>
  * ```
  */
-export function Text({
+function TextBase({
   children,
-  size = 'base',
-  weight = 'regular',
+  scope = 'main',
+  role = 'body',
   color = 'primary',
-  font = 'default',
-  lineHeight = 'normal',
+  size: sizeOverride,
   align,
   numberOfLines,
   elevation = 1,
   style,
-  // Accessibility
-  accessibilityRole,
-  // Testing & platform
+  accessibilityRole: accessibilityRoleOverride,
   testID,
   nativeID,
   ref,
+  responsive = false,
+  centerVertically = false,
+  features,
 }: TextProps) {
-  // Get the current theme's design tokens (colors, fonts, spacing).
-  // The elevation parameter affects which background shade the tokens reference.
   const tokens = useTokens(elevation);
+  const { config, reportingEndpoint } = useNewtoneTheme();
+
+  const size = sizeOverride ?? 'md';
+  const fontSlot = tokens.typography.fonts[scope];
+  // roleWeights from config (user-customized), falling back to canonical defaults
+  const resolvedFontWeight = config.typography.roleWeights?.[role] ?? ROLE_DEFAULT_WEIGHTS[role];
+
+  // --- Breakpoint-aware step ---
+  const breakpoint = useBreakpoint();
+  const baseStep = config.typography.roles[role][size];
+  const bpScale = BREAKPOINT_ROLE_SCALE[breakpoint][role];
+  const step = bpScale === 1.0 ? baseStep : scaleRoleStep(baseStep, bpScale);
+
+  // --- Responsive sizing (Layer 2 calibration) ---
+  // Hooks are called unconditionally; results are used only when `responsive && isAdaptive`.
+  const calibrations = useTypographyCalibrations();
+  const fontSlotFull = config.typography.fonts[scope]; // FontSlot with config.fallback
+  const localRatio = useLocalCalibration(
+    fontSlot.family,
+    SEMANTIC_WEIGHT_MAP.regular,
+    fontSlotFull.config.fallback,
+    calibrations[fontSlot.family],
+  );
+
+  const isAdaptive = ADAPTIVE_ROLES.has(role);
+  const [containerWidth, setContainerWidth] = useState<number | null>(null);
+  const characterCount = useMemo(() => extractCharacterCount(children), [children]);
+
+  const resolvedStep = useMemo(
+    () =>
+      resolveResponsiveSize(
+        {
+          role,
+          size,
+          responsive: responsive && isAdaptive,
+          fontFamily: fontSlot.family,
+          maxFontSize: step.fontSize,
+          minFontSize: Math.max(8, Math.round(step.fontSize * 0.7)),
+        },
+        config.typography.roles,
+        containerWidth != null ? { containerWidth, characterCount } : undefined,
+        { [fontSlot.family]: localRatio },
+      ),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [role, size, responsive, isAdaptive, fontSlot.family, step.fontSize, config.typography.roles, containerWidth, characterCount, localRatio],
+  );
+
+  // --- Layer 3: report observations for cross-site rolling averages ---
+  useEffect(() => {
+    if (!reportingEndpoint || !responsive || !isAdaptive || containerWidth == null) return;
+    const lineWidths = estimateLineWidths(characterCount, containerWidth, resolvedStep.fontSize, localRatio);
+    const lastLine = lineWidths[lineWidths.length - 1];
+    enqueueObservation(reportingEndpoint, {
+      fontFamily: fontSlot.family,
+      fontWeight: resolvedFontWeight,
+      role,
+      size,
+      fontSize: resolvedStep.fontSize,
+      containerWidth,
+      characterCount,
+      lineCount: lineWidths.length,
+      lastLineRatio: containerWidth > 0 ? lastLine / containerWidth : 1,
+    });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [reportingEndpoint, resolvedStep.fontSize, containerWidth]);
 
-  // Build the text style from the theme tokens.
-  // Wrapped in useMemo so it only recalculates when the inputs actually change,
-  // instead of recalculating on every render (which would be wasteful).
   const resolvedStyle = useMemo<TextStyle>(() => {
-    // Look up the pixel size for the chosen size token (e.g. 'base' → 16px).
-    const fontSize = tokens.typography.size[size];
+    const activeStep = responsive && isAdaptive ? resolvedStep : step;
+
+    // Font metrics corrections (adjustLineHeight, verticalCenterOffset, features)
+    const currentMetrics = config.typography.fontMetrics?.[fontSlot.family];
+
+    // Phase 3: Correct line height for font's natural vertical extent (snap to 4px grid)
+    const correctedLineHeight = currentMetrics
+      ? Math.round((activeStep.lineHeight * currentMetrics.naturalLineHeightRatio / REFERENCE_LINE_HEIGHT_RATIO) / 4) * 4
+      : activeStep.lineHeight;
+
+    // Phase 4: Visual centering correction (opt-in via centerVertically prop, snap to 0.5px)
+    const vcOffset = centerVertically && currentMetrics
+      ? Math.round(currentMetrics.verticalCenterOffset * activeStep.fontSize * 2) / 2
+      : 0;
+
+    // Phase 5: OpenType feature settings
+    const activeFeatures = features
+      ? (currentMetrics?.features ? features.filter(tag => currentMetrics.features.includes(tag)) : [...features])
+      : [];
+    const featureSettings = activeFeatures.length > 0 ? buildFontFeatureSettings(activeFeatures) : undefined;
+
     return {
-      // Font family from the theme (e.g. 'default' → 'Inter', 'mono' → 'JetBrains Mono').
-      fontFamily: tokens.typography.fonts[font],
-      fontSize,
-      // Font weight is stored as a number (e.g. 400, 600) but React Native expects a string.
-      fontWeight: String(tokens.typography.weight[weight]) as TextStyle['fontWeight'],
-      // Convert the theme color from internal sRGB format to a hex string (e.g. '#1a1a1a').
+      fontFamily: fontSlot.family,
+      fontSize: activeStep.fontSize,
+      fontWeight: String(resolvedFontWeight) as TextStyle['fontWeight'],
       color: resolveTextColor(color, tokens),
-      // Line height = font size × multiplier (e.g. 16px × 1.5 = 24px line height).
-      lineHeight: fontSize * tokens.typography.lineHeight[lineHeight],
+      lineHeight: correctedLineHeight,
       textAlign: align,
+      ...(vcOffset !== 0 ? { transform: [{ translateY: vcOffset }] } : {}),
+      ...(featureSettings ? { fontFeatureSettings: featureSettings } as any : {}),
     };
-  }, [tokens, size, weight, color, font, lineHeight, align]);
-
-  return (
-    <RNText
-      ref={ref}
-      testID={testID}
-      nativeID={nativeID}
-      accessibilityRole={accessibilityRole}
-      // If the user passed custom styles, merge them after the theme styles.
-      // The last style in the array wins, so user styles can override theme defaults.
-      // Normalize: the user can pass a single style or an array of styles.
-      style={style
-        ? [resolvedStyle, ...(Array.isArray(style) ? style : [style])]
-        : resolvedStyle
-      }
-      // When set, text is cut off after this many lines with "..." at the end.
-      numberOfLines={numberOfLines}
-    >
-      {children}
-    </RNText>
+  }, [tokens, fontSlot, step, resolvedStep, responsive, isAdaptive, resolvedFontWeight, color, align, config.typography.fontMetrics, centerVertically, features]);
+
+  // Auto-derive accessibility role and heading level for heading-like typography roles.
+  // react-native-web uses aria-level to render the correct <h1>/<h2>/<h3> element.
+  const inferredA11yRole = (role === 'headline' || role === 'title' || role === 'heading')
+    ? 'header' as const
+    : undefined;
+  const effectiveA11yRole = accessibilityRoleOverride ?? inferredA11yRole;
+  const ariaLevel = effectiveA11yRole === 'header' ? ROLE_HEADING_LEVEL[role] : undefined;
+
+  // Scope context value for span sub-components (stable reference — weights are constant)
+  const scopeCtx = useMemo(() => ({ weights: SEMANTIC_WEIGHT_MAP }), []);
+
+  const textNode = (
+    <TextScopeContext.Provider value={scopeCtx}>
+      <RNText
+        ref={ref}
+        testID={testID}
+        nativeID={nativeID}
+        accessibilityRole={effectiveA11yRole}
+        aria-level={ariaLevel}
+        style={style
+          ? [resolvedStyle, ...(Array.isArray(style) ? style : [style])]
+          : resolvedStyle
+        }
+        numberOfLines={numberOfLines}
+      >
+        {children}
+      </RNText>
+    </TextScopeContext.Provider>
   );
+
+  // Wrap in a View for container measurement when responsive mode is active on an adaptive role.
+  // onLayout fires whenever the container's dimensions change, providing the measured width.
+  if (responsive && isAdaptive) {
+    return (
+      <View
+        onLayout={(e: LayoutChangeEvent) => {
+          const w = e.nativeEvent.layout.width;
+          if (w > 0) setContainerWidth(w);
+        }}
+        style={{ width: '100%' }}
+      >
+        {textNode}
+      </View>
+    );
+  }
+
+  return textNode;
 }
+
+export { TextBase };

package/src/primitives/Text/Text.types.ts

@@ -1,20 +1,25 @@
 import type { Text as RNText, TextStyle } from 'react-native';
 import type { ElevationLevel } from '../../theme/types';
 
-/** Typography size tokens — maps to `tokens.typography.size.*` pixel values. */
-export type TextSize = 'xs' | 'sm' | 'base' | 'md' | 'lg' | 'xl' | 'xxl';
+/** Typography size step — selects within the current role's 3-step scale. @default 'md' */
+export type TextSize = 'sm' | 'md' | 'lg';
 
-/** Typography weight tokens — maps to `tokens.typography.weight.*` numeric values. */
-export type TextWeight = 'regular' | 'medium' | 'semibold' | 'bold';
+/** Font weight slots — maps to per-scope `tokens.typography.fonts[scope].weights.*` values. */
+export type TextWeight = 'regular' | 'medium' | 'bold';
 
 /** Semantic text color tokens — resolved from the current theme's token palette. */
 export type TextColor = 'primary' | 'secondary' | 'tertiary' | 'disabled' | 'accent' | 'success' | 'warning' | 'error';
 
-/** Font family tokens — maps to `tokens.typography.fonts.*` font stacks. */
-export type TextFont = 'default' | 'display' | 'mono';
+/** Font scope — selects which font family slot to use. @default 'main' */
+export type TextScope = 'main' | 'display' | 'mono' | 'currency';
 
-/** Line height multiplier tokens — maps to `tokens.typography.lineHeight.*` values. */
-export type TextLineHeight = 'tight' | 'normal' | 'relaxed';
+/**
+ * Semantic text role — determines default size, weight, and line height.
+ * Provides purpose-driven typography presets. Individual size/weight/lineHeight
+ * props can override the role's defaults when needed (e.g., in composites).
+ * @default 'body'
+ */
+export type TextRole = 'headline' | 'title' | 'heading' | 'subheading' | 'body' | 'label' | 'caption';
 
 /** Text alignment. */
 export type TextAlign = 'left' | 'center' | 'right';
@@ -22,38 +27,37 @@ export type TextAlign = 'left' | 'center' | 'right';
 /**
  * Props for Text — themed typography component.
  *
- * All visual properties are token-driven: size, weight, color, font,
- * and line height resolve from the current theme context. Use semantic
- * tokens rather than raw values for consistency.
+ * Primary API surface: `scope` (font family) + `role` (semantic preset) + `color`.
+ * Individual size/weight/lineHeight props are available as overrides for composites.
  *
  * @example
  * ```tsx
  * <Text>Default body text</Text>
- * <Text size="lg" weight="bold">Heading</Text>
- * <Text color="secondary" size="sm">Caption text</Text>
- * <Text font="mono" size="sm">const x = 42;</Text>
- * <Text numberOfLines={2}>Long text that truncates after two lines...</Text>
+ * <Text role="headline" scope="display">Hero title</Text>
+ * <Text role="label">Form label</Text>
+ * <Text scope="mono" role="caption">const x = 42;</Text>
+ * <Text role="body">Regular text with <Text.Bold>bold emphasis</Text.Bold></Text>
  * ```
  */
 export interface TextProps {
   /**
-   * Text content. Accepts strings, numbers, and nested `<Text>` elements
-   * for inline formatting (e.g., bold spans within a paragraph).
+   * Text content. Accepts strings, numbers, and span sub-components
+   * for inline formatting (e.g., `<Text.Bold>`, `<Text.Italic>`).
    *
    * @example
    * ```tsx
    * <Text>Plain string</Text>
    * <Text>Count: {42}</Text>
-   * <Text>Normal <Text weight="bold">bold</Text> normal</Text>
+   * <Text role="body">Normal <Text.Bold>bold</Text.Bold> normal</Text>
    * ```
    */
   readonly children: React.ReactNode;
 
-  /** Typography size token. @default 'base' */
-  readonly size?: TextSize;
+  /** Font scope — selects which font family to use. @default 'main' */
+  readonly scope?: TextScope;
 
-  /** Font weight token. @default 'regular' */
-  readonly weight?: TextWeight;
+  /** Semantic role — sets default size/weight/lineHeight. @default 'body' */
+  readonly role?: TextRole;
 
   /**
    * Semantic color token.
@@ -71,11 +75,10 @@ export interface TextProps {
    */
   readonly color?: TextColor;
 
-  /** Font family token. @default 'default' */
-  readonly font?: TextFont;
+  // ── Overrides (used by composites, not exposed in editor UI) ──
 
-  /** Line height multiplier token. @default 'normal' */
-  readonly lineHeight?: TextLineHeight;
+  /** Override the role's default size. */
+  readonly size?: TextSize;
 
   /** Text alignment. */
   readonly align?: TextAlign;
@@ -92,7 +95,8 @@ export interface TextProps {
   // ── Accessibility ──
 
   /**
-   * Semantic role for screen readers.
+   * Semantic role for screen readers. Auto-inferred from typography role
+   * (headline/title/heading → 'header') unless explicitly set.
    *
    * - `'header'` — Marks this as a heading (e.g. page title, section header)
    * - `'text'` — Default text role (usually omitted)
@@ -110,4 +114,53 @@ export interface TextProps {
 
   /** Ref to the underlying React Native Text element. */
   readonly ref?: React.Ref<RNText>;
+
+  /**
+   * Enable responsive font sizing for adaptive roles (headline, title, heading, subheading).
+   * When true, the Text component measures its container width and uses `resolveResponsiveSize`
+   * to pick the best fontSize within the role's natural size, improving line-break quality.
+   * Requires the text to be wrapped in a container that defines a width.
+   * No-op for non-adaptive roles (body, label, caption).
+   * @default false
+   */
+  readonly responsive?: boolean;
+
+  /**
+   * Apply vertical centering correction to compensate for font metrics.
+   * Shifts text down by the font's verticalCenterOffset so that cap-height
+   * text appears visually centered within flex containers (buttons, chips).
+   * No-op for multi-line body text — only enable in single-line centering contexts.
+   * Requires fontMetrics in the theme config; ignored when metrics are unavailable.
+   * @default false
+   */
+  readonly centerVertically?: boolean;
+
+  /**
+   * OpenType feature tags to enable (e.g., `['tnum', 'kern']`).
+   * When fontMetrics are available, requested tags are filtered against the font's
+   * supported features. When metrics are unavailable, all tags are applied optimistically.
+   * Maps to the CSS `font-feature-settings` property via react-native-web.
+   */
+  readonly features?: readonly string[];
+}
+
+/**
+ * Constrained props for inline span sub-components (Text.Bold, Text.Italic, etc.).
+ * Spans inherit font family, size, and line height from the parent Text.
+ * Only inline formatting properties are exposed.
+ */
+export interface TextSpanProps {
+  readonly children: React.ReactNode;
+  /** Override text color within the span. */
+  readonly color?: TextColor;
+  /** Override font weight within the span. */
+  readonly weight?: TextWeight;
+  /** Apply italic style. */
+  readonly italic?: boolean;
+  /** Apply underline decoration. */
+  readonly underline?: boolean;
+  /** Apply background highlight using a semantic color token. */
+  readonly highlight?: TextColor;
+  /** Style overrides (applied last). */
+  readonly style?: TextStyle | readonly TextStyle[];
 }

package/src/primitives/Text/index.ts

@@ -1,10 +1,34 @@
-export { Text } from './Text';
+import { TextBase } from './Text';
+import { TextSpan, TextBold, TextMedium, TextItalic, TextUnderline, TextHighlight } from './Text.spans';
+
+/**
+ * Token-aware text primitive with span sub-components.
+ *
+ * Primary API: `scope` (font family) + `role` (semantic preset) + `color`.
+ *
+ * @example
+ * ```tsx
+ * <Text role="headline" scope="display">Hero</Text>
+ * <Text role="body">Regular <Text.Bold>bold</Text.Bold> text</Text>
+ * <Text role="label" color="secondary">Field label</Text>
+ * ```
+ */
+export const Text = Object.assign(TextBase, {
+  Span: TextSpan,
+  Bold: TextBold,
+  Medium: TextMedium,
+  Italic: TextItalic,
+  Underline: TextUnderline,
+  Highlight: TextHighlight,
+});
+
 export type {
   TextProps,
   TextSize,
   TextWeight,
   TextColor,
-  TextFont,
-  TextLineHeight,
+  TextScope,
+  TextRole,
   TextAlign,
+  TextSpanProps,
 } from './Text.types';

package/src/primitives/index.ts

@@ -40,7 +40,8 @@ export type {
   TextSize,
   TextWeight,
   TextColor,
-  TextFont,
-  TextLineHeight,
+  TextScope,
+  TextRole,
+  TextSpanProps,
   TextAlign,
 } from './Text';

package/src/registry/codegen.ts

@@ -18,6 +18,7 @@ const HANDLER_PROPS: Record<string, readonly string[]> = {
  */
 const CHILDREN_CONTENT: Record<string, string> = {
   button: 'Button',
+  text: 'The quick brown fox',
   card: '{/* content */}',
   frame: '{/* content */}',
 };

package/src/registry/icons.ts

@@ -0,0 +1,111 @@
+export interface IconCatalogCategory {
+  readonly id: string;
+  readonly label: string;
+  readonly icons: readonly string[];
+}
+
+export const ICON_CATALOG: readonly IconCatalogCategory[] = [
+  {
+    id: 'navigation',
+    label: 'Navigation',
+    icons: [
+      'home', 'menu', 'close', 'arrow_back', 'arrow_forward',
+      'arrow_upward', 'arrow_downward', 'chevron_left', 'chevron_right',
+      'expand_more', 'expand_less', 'first_page', 'last_page',
+      'more_vert', 'more_horiz', 'unfold_more', 'unfold_less',
+      'subdirectory_arrow_right',
+    ],
+  },
+  {
+    id: 'actions',
+    label: 'Actions',
+    icons: [
+      'search', 'settings', 'done', 'add', 'remove',
+      'delete', 'edit', 'save', 'refresh', 'undo',
+      'redo', 'download', 'upload', 'share', 'print',
+      'content_copy', 'content_paste', 'open_in_new', 'launch',
+      'drag_indicator', 'tune', 'sort', 'filter_list',
+    ],
+  },
+  {
+    id: 'communication',
+    label: 'Communication',
+    icons: [
+      'mail', 'chat', 'call', 'notifications', 'forum',
+      'send', 'inbox', 'drafts', 'mark_email_read',
+      'contact_mail', 'alternate_email', 'comment',
+      'chat_bubble', 'sms', 'voicemail',
+    ],
+  },
+  {
+    id: 'content',
+    label: 'Content',
+    icons: [
+      'add_circle', 'remove_circle', 'check_circle', 'cancel',
+      'flag', 'bookmark', 'star', 'favorite',
+      'thumb_up', 'thumb_down', 'push_pin', 'link',
+      'link_off', 'bolt', 'label', 'inventory_2',
+      'visibility', 'visibility_off',
+    ],
+  },
+  {
+    id: 'media',
+    label: 'Media',
+    icons: [
+      'play_arrow', 'pause', 'stop', 'skip_next', 'skip_previous',
+      'fast_forward', 'fast_rewind', 'replay', 'shuffle',
+      'repeat', 'volume_up', 'volume_off', 'music_note',
+      'image', 'photo_camera', 'videocam', 'mic',
+    ],
+  },
+  {
+    id: 'file',
+    label: 'File & Folder',
+    icons: [
+      'folder', 'folder_open', 'create_new_folder', 'description',
+      'file_copy', 'attach_file', 'cloud', 'cloud_upload',
+      'cloud_download', 'cloud_off', 'storage', 'snippet_folder',
+    ],
+  },
+  {
+    id: 'social',
+    label: 'Social & People',
+    icons: [
+      'person', 'group', 'person_add', 'person_remove',
+      'people', 'face', 'sentiment_satisfied', 'sentiment_dissatisfied',
+      'public', 'workspace_premium', 'emoji_events', 'military_tech',
+    ],
+  },
+  {
+    id: 'alerts',
+    label: 'Alerts & Status',
+    icons: [
+      'error', 'warning', 'info', 'help',
+      'check_circle', 'report', 'new_releases',
+      'notification_important', 'priority_high',
+      'verified', 'shield', 'security',
+      'lock', 'lock_open',
+    ],
+  },
+  {
+    id: 'device',
+    label: 'Device & Hardware',
+    icons: [
+      'phone_android', 'computer', 'tablet_mac', 'watch',
+      'keyboard', 'mouse', 'headphones', 'speaker',
+      'monitor', 'devices', 'memory', 'battery_full',
+      'wifi', 'bluetooth', 'usb', 'dark_mode', 'light_mode',
+    ],
+  },
+  {
+    id: 'editor',
+    label: 'Editor & Formatting',
+    icons: [
+      'format_bold', 'format_italic', 'format_underlined',
+      'format_list_bulleted', 'format_list_numbered', 'format_quote',
+      'format_align_left', 'format_align_center', 'format_align_right',
+      'title', 'text_fields', 'code', 'palette',
+      'color_lens', 'brush', 'auto_fix_high',
+    ],
+  },
+];

package/src/registry/index.ts

@@ -15,3 +15,6 @@ export {
 } from './registry';
 
 export { generateComponentCode } from './codegen';
+
+export type { IconCatalogCategory } from './icons';
+export { ICON_CATALOG } from './icons';