From d53ef30f4f330d9e6d4cd3548a6eebd518325755 Mon Sep 17 00:00:00 2001
From: Mahmoud Zalt <mahmoud@zalt.me>
Date: Sat, 6 Dec 2025 02:36:37 +0100
Subject: [PATCH 1/2] Add Image component documentation and stories

- Introduced Image.mdx for detailed usage and examples, including loading, error handling, and draggable functionality.
- Created Image.stories.tsx to showcase various states of the Image component, including base, loading, error, force render on error, and draggable scenarios.
---
 src/components/Image/Image.mdx         |  48 +++++++++++
 src/components/Image/Image.stories.tsx | 105 +++++++++++++++++++++++++
 2 files changed, 153 insertions(+)
 create mode 100644 src/components/Image/Image.mdx
 create mode 100644 src/components/Image/Image.stories.tsx

diff --git a/src/components/Image/Image.mdx b/src/components/Image/Image.mdx
new file mode 100644
index 0000000..b146a8b
--- /dev/null
+++ b/src/components/Image/Image.mdx
@@ -0,0 +1,48 @@
+import { Canvas, ArgTypes, Meta, Subtitle, Title } from '@storybook/blocks';
+import { linkTo } from '@storybook/addon-links';
+import * as ImageStories from './Image.stories';
+
+<Meta of={ImageStories} />
+
+<Title>Image</Title>
+<Subtitle>Load remote images with fade-in animation and error handling</Subtitle>
+
+## Usage
+```jsx
+import { Image } from "@openai/apps-sdk-ui/components/Image";
+```
+
+<Canvas of={ImageStories.Base} additionalActions={[
+  { title: 'View story', onClick: linkTo(ImageStories.title, 'Base')}
+]} />
+
+## Reference
+
+<ArgTypes of={ImageStories.Base} exclude={['ref']} />
+
+## Examples
+
+### Loading
+
+Images fade in smoothly once loaded. The component tracks loaded images to provide instant display on subsequent renders.
+
+<Canvas of={ImageStories.Loading} />
+
+### Error
+
+By default, if an image fails to load, the component returns `null` and nothing is rendered.
+
+<Canvas of={ImageStories.Error} />
+
+### Force render on error
+
+Use `forceRenderAfterLoadFail` to display the broken image icon when an image fails to load, rather than hiding it completely.
+
+<Canvas of={ImageStories.ForceRenderOnError} />
+
+### Draggable
+
+Control whether the image can be dragged by setting the `draggable` prop.
+
+<Canvas of={ImageStories.Draggable} />
+
diff --git a/src/components/Image/Image.stories.tsx b/src/components/Image/Image.stories.tsx
new file mode 100644
index 0000000..dc6bcef
--- /dev/null
+++ b/src/components/Image/Image.stories.tsx
@@ -0,0 +1,105 @@
+import { type Meta } from "@storybook/react"
+import { type ComponentProps } from "react"
+import { Image } from "./"
+
+type ImageProps = ComponentProps<"img"> & {
+  forceRenderAfterLoadFail?: boolean
+}
+
+const meta = {
+  title: "Components/Image",
+  component: Image,
+  args: {
+    src: "https://picsum.photos/400/300",
+    draggable: false,
+    forceRenderAfterLoadFail: false,
+  },
+  argTypes: {
+    src: { control: "text" },
+    className: { control: false },
+    onLoad: { control: false },
+    onError: { control: false },
+  },
+} satisfies Meta<typeof Image>
+
+export default meta
+
+export const Base = (args: ImageProps) => <Image {...args} />
+
+export const Loading = () => (
+  <div className="w-[400px]">
+    <Image src="https://picsum.photos/400/300?random=1" alt="Example image" />
+  </div>
+)
+
+Loading.parameters = {
+  docs: {
+    source: {
+      code: `<Image src="https://picsum.photos/400/300" alt="Example image" />`,
+    },
+  },
+}
+
+export const Error = () => (
+  <div className="w-[400px]">
+    <Image
+      src="https://invalid-url-that-does-not-exist.com/image.jpg"
+      alt="This will fail to load"
+    />
+  </div>
+)
+
+Error.parameters = {
+  docs: {
+    source: {
+      code: `<Image src="https://invalid-url-that-does-not-exist.com/image.jpg" alt="This will fail to load" />`,
+    },
+    description: {
+      story: "When an image fails to load, the component returns `null` and nothing is rendered.",
+    },
+  },
+}
+
+export const ForceRenderOnError = () => (
+  <div className="w-[400px]">
+    <Image
+      src="https://invalid-url-that-does-not-exist.com/image.jpg"
+      alt="This will fail to load"
+      forceRenderAfterLoadFail
+    />
+  </div>
+)
+
+ForceRenderOnError.parameters = {
+  docs: {
+    source: {
+      code: `<Image
+  src="https://invalid-url-that-does-not-exist.com/image.jpg"
+  alt="This will fail to load"
+  forceRenderAfterLoadFail
+/>`,
+    },
+    description: {
+      story:
+        "Use `forceRenderAfterLoadFail` to display the broken image icon when an image fails to load.",
+    },
+  },
+}
+
+export const Draggable = (args: ImageProps) => (
+  <div className="w-[400px]">
+    <Image {...args} draggable alt="Draggable image" />
+  </div>
+)
+
+Draggable.args = {
+  draggable: true,
+}
+
+Draggable.parameters = {
+  docs: {
+    source: {
+      code: `<Image src="https://picsum.photos/400/300" draggable alt="Draggable image" />`,
+    },
+  },
+}

From e7e566f3bca21c660e4e3e8d2208661dc67a33b4 Mon Sep 17 00:00:00 2001
From: Mahmoud Zalt <mahmoud@zalt.me>
Date: Sat, 6 Dec 2025 02:38:06 +0100
Subject: [PATCH 2/2] Add Icon component documentation and stories

- Introduced Icon.mdx for detailed usage, examples, and reference for the Icon component.
- Created Icon.stories.tsx to showcase various states of the Icon component, including sizing, colors, common icons, and usage alongside text.
---
 src/components/Icon/Icon.mdx         | 53 ++++++++++++++++++
 src/components/Icon/Icon.stories.tsx | 80 ++++++++++++++++++++++++++++
 2 files changed, 133 insertions(+)
 create mode 100644 src/components/Icon/Icon.mdx
 create mode 100644 src/components/Icon/Icon.stories.tsx

diff --git a/src/components/Icon/Icon.mdx b/src/components/Icon/Icon.mdx
new file mode 100644
index 0000000..f03c318
--- /dev/null
+++ b/src/components/Icon/Icon.mdx
@@ -0,0 +1,53 @@
+import { Canvas, ArgTypes, Meta, Subtitle, Title } from '@storybook/blocks';
+import { linkTo } from '@storybook/addon-links';
+import * as IconStories from './Icon.stories';
+
+<Meta of={IconStories} />
+
+<Title>Icon</Title>
+<Subtitle>Collection of SVG icons exported as React components</Subtitle>
+
+## Usage
+
+```jsx
+import { Search, Settings, Check } from "@openai/apps-sdk-ui/components/Icon";
+```
+
+<Canvas of={IconStories.Base} additionalActions={[
+  { title: 'View story', onClick: linkTo(IconStories.title, 'Base')}
+]} />
+
+## Reference
+
+<ArgTypes of={IconStories.Base} exclude={['ref']} />
+
+## Examples
+
+### Sizing
+
+Icons accept `width` and `height` props to control their size. By default, icons use `1em` which scales with the font size.
+
+<Canvas of={IconStories.Sizing} />
+
+### Colors
+
+Icons use `currentColor` for their fill, so they inherit the text color from their parent. You can style them using Tailwind color classes.
+
+<Canvas of={IconStories.Colors} />
+
+### Common icons
+
+A selection of commonly used icons from the collection.
+
+<Canvas of={IconStories.CommonIcons} />
+
+### With text
+
+Icons work well alongside text content, inheriting the text color and scaling appropriately.
+
+<Canvas of={IconStories.WithText} />
+
+## Icon gallery
+
+For a complete list of all available icons, see the [Icon Gallery](/foundations-icons).
+
diff --git a/src/components/Icon/Icon.stories.tsx b/src/components/Icon/Icon.stories.tsx
new file mode 100644
index 0000000..b9c982d
--- /dev/null
+++ b/src/components/Icon/Icon.stories.tsx
@@ -0,0 +1,80 @@
+import { type Meta } from "@storybook/react"
+import { type ComponentProps } from "react"
+import { ArrowRight, Check, Copy, Robot, Search, Settings } from "./"
+
+type IconProps = ComponentProps<typeof Search>
+
+const meta = {
+  title: "Components/Icon",
+  component: Search,
+  args: {
+    width: 24,
+    height: 24,
+  },
+  argTypes: {
+    className: { control: false },
+  },
+} satisfies Meta<typeof Search>
+
+export default meta
+
+export const Base = (args: IconProps) => <Search {...args} />
+
+export const Sizing = () => (
+  <div className="flex items-center gap-6">
+    <div className="flex flex-col items-center gap-2">
+      <Search width={16} height={16} />
+      <span className="text-sm text-tertiary">16px</span>
+    </div>
+    <div className="flex flex-col items-center gap-2">
+      <Search width={24} height={24} />
+      <span className="text-sm text-tertiary">24px</span>
+    </div>
+    <div className="flex flex-col items-center gap-2">
+      <Search width={32} height={32} />
+      <span className="text-sm text-tertiary">32px</span>
+    </div>
+    <div className="flex flex-col items-center gap-2">
+      <Search width={48} height={48} />
+      <span className="text-sm text-tertiary">48px</span>
+    </div>
+  </div>
+)
+
+export const Colors = () => (
+  <div className="flex items-center gap-6">
+    <Search className="text-primary" width={24} height={24} />
+    <Search className="text-success" width={24} height={24} />
+    <Search className="text-warning" width={24} height={24} />
+    <Search className="text-danger" width={24} height={24} />
+    <Search className="text-tertiary" width={24} height={24} />
+  </div>
+)
+
+export const CommonIcons = () => (
+  <div className="flex items-center gap-4">
+    <Search width={20} height={20} />
+    <Settings width={20} height={20} />
+    <Check width={20} height={20} />
+    <Copy width={20} height={20} />
+    <ArrowRight width={20} height={20} />
+    <Robot width={20} height={20} />
+  </div>
+)
+
+export const WithText = () => (
+  <div className="flex flex-col gap-4">
+    <div className="flex items-center gap-2">
+      <Search width={18} height={18} />
+      <span>Search</span>
+    </div>
+    <div className="flex items-center gap-2">
+      <Settings width={18} height={18} />
+      <span>Settings</span>
+    </div>
+    <div className="flex items-center gap-2">
+      <Check width={18} height={18} />
+      <span>Complete</span>
+    </div>
+  </div>
+)