fix(ui): Add IconFrame

.changeset/tidy-icons-frame.md

@@ -0,0 +1,2 @@
+---
+---

packages/swingset/src/components/DocsViewer.tsx

@@ -52,6 +52,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
     'alert-dialog': dynamic(() => import('../stories/alert-dialog.component.mdx')),
     heading: dynamic(() => import('../stories/heading.mdx')),
     icon: dynamic(() => import('../stories/icon.mdx')),
+    'icon-frame': dynamic(() => import('../stories/icon-frame.mdx')),
     menu: dynamic(() => import('../stories/menu.component.mdx')),
     otp: dynamic(() => import('../stories/otp.component.mdx')),
     popover: dynamic(() => import('../stories/popover.component.mdx')),

packages/swingset/src/lib/registry.ts

@@ -53,6 +53,14 @@ import {
   Override as IconOverride,
   Sizes as IconSizes,
 } from '../stories/icon.stories';
+import {
+  BrandIcons as IconFrameBrandIcons,
+  CustomSurface as IconFrameCustomSurface,
+  Default as IconFrameDefault,
+  meta as iconFrameMeta,
+  Sizes as IconFrameSizes,
+  Treatments as IconFrameTreatments,
+} from '../stories/icon-frame.stories';
 import {
   Default,
   Disabled as InputDisabled,
@@ -98,6 +106,7 @@ import {
   ConnectedAccounts as SectionConnectedAccounts,
   Default as SectionDefault,
   Destructive as SectionDestructive,
+  IconFrameMedia as SectionIconFrameMedia,
   meta as sectionMeta,
   MultipleEmailAndPhoneNumbers as SectionMultipleEmailAndPhoneNumbers,
 } from '../stories/section.stories';
@@ -193,6 +202,7 @@ const sectionModule: StoryModule = {
   Default: SectionDefault,
   MultipleEmailAndPhoneNumbers: SectionMultipleEmailAndPhoneNumbers,
   ConnectedAccounts: SectionConnectedAccounts,
+  IconFrameMedia: SectionIconFrameMedia,
   Destructive: SectionDestructive,
 };
 const dialogComponentModule: StoryModule = { meta: dialogComponentMeta, Default: DialogDefault };
@@ -288,6 +298,15 @@ const iconModule: StoryModule = {
   Override: IconOverride,
 };
 
+const iconFrameModule: StoryModule = {
+  meta: iconFrameMeta,
+  Default: IconFrameDefault,
+  Sizes: IconFrameSizes,
+  Treatments: IconFrameTreatments,
+  CustomSurface: IconFrameCustomSurface,
+  BrandIcons: IconFrameBrandIcons,
+};
+
 // Headless primitives carry just `meta` (no story functions). Like every component
 // they're documented as a single overview page; their live demos come from `<Story>` /
 // `<Preview>` embeds in the MDX, which import the stories module directly.
@@ -431,6 +450,7 @@ export const registry: StoryModule[] = [
   alertDialogComponentModule,
   headingModule,
   iconModule,
+  iconFrameModule,
   menuComponentModule,
   otpComponentModule,
   popoverComponentModule,

packages/swingset/src/stories/icon-frame.mdx

@@ -0,0 +1,70 @@
+import * as IconFrameStories from './icon-frame.stories';
+
+# IconFrame
+
+IconFrame centers an icon or other visual in a square Mosaic surface. `bordered` and `filled` are independent treatments, while `size` controls the frame dimensions. The default is a bordered 40px frame; the filled treatment uses a 6% black scrim in light mode and a 6% white scrim in dark mode.
+
+## Playground
+
+<Preview
+  name='Default'
+  storyModule={IconFrameStories}
+/>
+
+## Props
+
+<PropTable
+  meta={IconFrameStories.meta}
+  extra={[{ name: 'render', type: '(props) => ReactNode' }]}
+/>
+
+## Usage
+
+```tsx
+import { Icon, IconFrame } from '@clerk/ui/mosaic/components/icon';
+
+<IconFrame
+  bordered={false}
+  filled
+  size='lg'
+>
+  <Icon name='check' />
+</IconFrame>
+```
+
+---
+
+## Examples
+
+### Sizes
+
+<Story
+  name='Sizes'
+  storyModule={IconFrameStories}
+  composition={[{ name: 'Icon', href: '/components/icon', layer: 'Components' }]}
+/>
+
+`sm`, `md`, `lg`, and `xl` map to 28px, 32px, 36px, and 40px respectively.
+
+### Treatments
+
+<Story
+  name='Treatments'
+  storyModule={IconFrameStories}
+/>
+
+`bordered` and `filled` can be used separately, together, or both disabled for a centered bare icon.
+
+### Custom surface
+
+<Story
+  name='CustomSurface'
+  storyModule={IconFrameStories}
+/>
+
+### Brand icons
+
+<Story
+  name='BrandIcons'
+  storyModule={IconFrameStories}
+/>

packages/swingset/src/stories/icon-frame.stories.tsx

@@ -0,0 +1,138 @@
+import type { IconFrameProps } from '@clerk/ui/mosaic/components/icon';
+import { Icon, IconFrame } from '@clerk/ui/mosaic/components/icon';
+import { colorVars, space } from '@clerk/ui/mosaic/styles';
+
+import type { StoryMeta } from '@/lib/types';
+
+export { default as __source } from './icon-frame.stories?raw';
+
+const providerIconUrl = (provider: string) => `https://img.clerk.com/static/${provider}.svg`;
+
+function ProviderLogo({ provider }: { provider: string }) {
+  return (
+    <img
+      alt=''
+      src={providerIconUrl(provider)}
+      style={{ display: 'block', height: space['5'], objectFit: 'contain', width: space['5'] }}
+    />
+  );
+}
+
+export const meta: StoryMeta = {
+  group: 'Components',
+  title: 'IconFrame',
+  source: 'packages/ui/src/mosaic/components/icon/icon-frame.tsx',
+  styles: {
+    _variants: {
+      bordered: { true: {}, false: {} },
+      filled: { true: {}, false: {} },
+      size: { sm: {}, md: {}, lg: {}, xl: {} },
+    },
+    _defaultVariants: {
+      bordered: true,
+      filled: false,
+      size: 'xl',
+    },
+  },
+};
+
+function knobsAsProps(props: Record<string, unknown>) {
+  return props as unknown as IconFrameProps;
+}
+
+export function Default(props: Record<string, unknown>) {
+  return (
+    <IconFrame {...knobsAsProps(props)}>
+      <Icon name='check' />
+    </IconFrame>
+  );
+}
+
+export function Sizes() {
+  return (
+    <div style={{ alignItems: 'center', display: 'flex', gap: 12 }}>
+      <IconFrame size='sm'>
+        <Icon
+          name='check'
+          size='sm'
+        />
+      </IconFrame>
+      <IconFrame size='md'>
+        <Icon
+          name='check'
+          size='md'
+        />
+      </IconFrame>
+      <IconFrame size='lg'>
+        <Icon
+          name='check'
+          size='md'
+        />
+      </IconFrame>
+      <IconFrame size='xl'>
+        <Icon
+          name='check'
+          size='lg'
+        />
+      </IconFrame>
+    </div>
+  );
+}
+
+export function Treatments() {
+  return (
+    <div style={{ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: 12 }}>
+      <IconFrame
+        aria-label='Unframed'
+        bordered={false}
+      >
+        <Icon name='check' />
+      </IconFrame>
+      <IconFrame aria-label='Bordered'>
+        <Icon name='check' />
+      </IconFrame>
+      <IconFrame
+        aria-label='Filled'
+        bordered={false}
+        filled
+      >
+        <Icon name='check' />
+      </IconFrame>
+      <IconFrame
+        aria-label='Bordered and filled'
+        filled
+      >
+        <Icon name='check' />
+      </IconFrame>
+    </div>
+  );
+}
+
+export function CustomSurface() {
+  return (
+    <IconFrame
+      style={{
+        backgroundColor: colorVars['--cl-color-primary'],
+        color: colorVars['--cl-color-primary-foreground'],
+      }}
+    >
+      <Icon
+        name='check'
+        size='lg'
+      />
+    </IconFrame>
+  );
+}
+
+export function BrandIcons() {
+  return (
+    <div style={{ alignItems: 'center', display: 'flex', gap: 12 }}>
+      <IconFrame aria-label='Google'>
+        <ProviderLogo provider='google' />
+      </IconFrame>
+      <IconFrame aria-label='MetaMask'>
+        <ProviderLogo provider='metamask' />
+      </IconFrame>
+    </div>
+  );
+}

packages/swingset/src/stories/section.mdx

@@ -64,6 +64,17 @@ Use `Section.Items` for a nested value list beneath a row's header item. The row
   ]}
 />
 
+### Framed icon media
+
+<Story
+  name='IconFrameMedia'
+  storyModule={SectionStories}
+  composition={[
+    { name: 'IconFrame', href: '/components/icon-frame', layer: 'Components' },
+    { name: 'Icon', href: '/components/icon', layer: 'Components' },
+  ]}
+/>
+
 ### Destructive section
 
 <Story

packages/swingset/src/stories/section.stories.tsx

@@ -1,42 +1,26 @@
 import { Avatar } from '@clerk/ui/mosaic/components/avatar';
 import { Badge } from '@clerk/ui/mosaic/components/badge';
 import { Button } from '@clerk/ui/mosaic/components/button';
-import { Icon } from '@clerk/ui/mosaic/components/icon';
+import { Icon, IconFrame } from '@clerk/ui/mosaic/components/icon';
 import { Section } from '@clerk/ui/mosaic/components/section';
-import * as stylex from '@stylexjs/stylex';
+import { space } from '@clerk/ui/mosaic/styles';
 
 import type { StoryMeta } from '@/lib/types';
 
 export { default as __source } from './section.stories?raw';
 
 const providerIconUrl = (provider: string) => `https://img.clerk.com/static/${provider}.svg`;
 
-const styles = stylex.create({
-  providerMedia: {
-    backgroundColor: 'var(--cl-color-background)',
-    borderColor: 'light-dark(var(--cl-color-border-faded), var(--cl-color-background))',
-    borderRadius: 'var(--cl-radius-lg)',
-    borderStyle: 'solid',
-    borderWidth: '1px',
-  },
-  providerIcon: {
-    display: 'block',
-    height: '20px',
-    width: '20px',
-  },
-});
-
-function ProviderIcon({ provider }: { provider: string }) {
+function ProviderMedia({ provider }: { provider: string }) {
   return (
-    <Section.Media
-      size='lg'
-      {...stylex.props(styles.providerMedia)}
-    >
-      <img
-        alt=''
-        src={providerIconUrl(provider)}
-        {...stylex.props(styles.providerIcon)}
-      />
+    <Section.Media size='lg'>
+      <IconFrame>
+        <img
+          alt=''
+          src={providerIconUrl(provider)}
+          style={{ display: 'block', height: space['5'], width: space['5'] }}
+        />
+      </IconFrame>
     </Section.Media>
   );
 }
@@ -308,7 +292,7 @@ export function ConnectedAccounts() {
       <Section.Group>
         <Section.Row>
           <Section.Item>
-            <ProviderIcon provider='google' />
+            <ProviderMedia provider='google' />
             <Section.Content>
               <Section.Label>Google</Section.Label>
               <Section.Description>test@google.com</Section.Description>
@@ -328,7 +312,7 @@ export function ConnectedAccounts() {
         </Section.Row>
         <Section.Row>
           <Section.Item>
-            <ProviderIcon provider='apple' />
+            <ProviderMedia provider='apple' />
             <Section.Content>
               <Section.Label>Apple</Section.Label>
             </Section.Content>
@@ -353,6 +337,32 @@ export function ConnectedAccounts() {
   );
 }
 
+export function IconFrameMedia() {
+  return (
+    <Section.Root style={{ maxWidth: 560 }}>
+      <Section.Title>Team</Section.Title>
+      <Section.Group>
+        <Section.Row>
+          <Section.Item>
+            <Section.Media size='lg'>
+              <IconFrame>
+                <Icon
+                  name='users'
+                  size='lg'
+                />
+              </IconFrame>
+            </Section.Media>
+            <Section.Content>
+              <Section.Label>Engineering</Section.Label>
+              <Section.Description>12 members</Section.Description>
+            </Section.Content>
+          </Section.Item>
+        </Section.Row>
+      </Section.Group>
+    </Section.Root>
+  );
+}
+
 export function Destructive() {
   return (
     <Section.Root>